# shridarpatil/whatomate architecture

> Architecture diagram of the GitHub repository shridarpatil/whatomate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shridarpatil/whatomate
- Repository: https://github.com/shridarpatil/whatomate

## Overview

1. **Top-level shape**
   Whatomate is a **single Go binary** that serves the backend API and, in production, embeds the built frontend assets. The repo is split into a Go backend, a Vue 3 frontend, documentation, Docker packaging, and end-to-end tests.

2. **Runtime modes**
   The executable under `cmd/whatomate` supports multiple modes: `server` runs the API plus a worker process, `worker` runs background jobs only, and `version` reports build info. This is an important architectural boundary because operational scaling can split request handling from async processing without changing the codebase.

3. **Backend core**
   The backend lives under `internal/` and is organized by capability rather than by technical layer. Request handlers are in `internal/handlers`, domain models in `internal/models`, and supporting subsystems such as calling, queueing, websocket delivery, storage, crypto, and templating are separated into their own packages.

4. **HTTP/API layer**
   `internal/handlers` is the main application surface. It contains resource endpoints for auth, organizations, users, roles, teams, contacts, tags, templates, campaigns, chat, analytics, webhooks, and calling-related resources. Middleware for CSRF and rate limiting sits in `internal/middleware`, so cross-cutting concerns are enforced centrally before handlers run.

5. **Persistence and state**
   The app uses **PostgreSQL** as the primary database and **Redis** for cache/pubsub/queue coordination. Database access is abstracted under `internal/database`; Redis-backed behavior appears in `internal/database/redis.go`, `internal/queue`, `internal/assignment/cache.go`, `internal/calling/cache.go`, and parts of the websocket and worker subsystems. This suggests a split between durable business data and transient coordination state.

6. **Multi-tenant and authorization model**
   The domain is explicitly multi-tenant: organizations are first-class, and permissions are enforced through roles, teams, and scoped access control. The frontend has dedicated settings pages for organizations, roles, permissions, users, teams, and API keys, while backend handlers mirror those entities. The architecture therefore centers on tenant-scoped data access and admin-managed governance.

7. **Real-time communication**
   WebSocket support is a dedicated subsystem under `internal/websocket` and a matching client store in the frontend. It likely powers live chat, agent presence, and call/chat updates. Real-time state is coordinated through a hub/client model, with Redis/pubsub used where cross-process fanout is needed.

8. **WhatsApp integration boundary**
   External integration with the **WhatsApp Cloud API** is isolated in `pkg/whatsapp`. That package handles messages, templates, flows, webhooks, catalog, calls, and analytics payloads. The backend handlers call into this integration layer, which keeps provider-specific API details separated from app domain logic.

9. **Chat, chatbot, and automation flows**
   Automation is represented by several related subsystems: chatbot handlers, a flow processor, flow-builder UI, condition evaluation, simulation/history composables, and AI-context pages. The repo supports keyword-based replies, visual flows, transfers, and API-driven or AI-assisted responses. This is a major business subsystem with both persisted definitions and runtime execution.

10. **Calling and IVR**
   Voice/calling is another distinct subsystem under `internal/calling` with IVR, transfers, outgoing calls, DTMF, audio, recording, and WebRTC-related handling. The frontend includes a call flow editor and call control UI, while tests cover call logs, transfers, IVR flows, and team assignment. Architecturally, calling is not just a feature flag; it is its own operational path with session state and media handling.

11. **Asynchronous processing**
   Background work is handled by `internal/worker` plus `internal/queue`. This is where retryable tasks, message dispatch, campaign fanout, webhook dispatch, SLA processing, and other deferred jobs likely run. The separation from the HTTP server allows the app to handle bursty workloads such as campaigns and message retries without blocking request traffic.

12. **Frontend application**
   The frontend under `frontend/` is a **Vue 3 SPA** built with Vite, Tailwind, and shadcn-vue-style UI primitives. It is organized by feature views matching backend domains: dashboard, chat, chatbot, calling, analytics, settings, and auth. Shared components, composables, Pinia stores, router config, and websocket/API service layers form the client-side architecture.

13. **Build and deployment packaging**
   Docker is a first-class deployment path. The repo includes Dockerfiles for standard and release builds, a compose stack, and GitHub Actions for testing, docs deployment, release publishing, and image builds. The Go backend embeds the built frontend from `internal/frontend/dist`, which is the key packaging boundary for production.

14. **Documentation and validation**
   Documentation is a separate Astro site under `docs/`, and end-to-end tests are maintained in `frontend/e2e` with Playwright. The test suite covers auth, settings, chat, campaigns, calling, chatbot, analytics, i18n, and permissions, which reflects the product’s domain breadth and helps validate the main user flows across the frontend-backend boundary.

Main entry points: [`internal/handlers`](https://github.com/shridarpatil/whatomate/tree/main/internal/handlers) (Handlers), [`frontend/src`](https://github.com/shridarpatil/whatomate/tree/main/frontend/src) (SPA), [`internal/worker`](https://github.com/shridarpatil/whatomate/tree/main/internal/worker) (Worker), [`internal/websocket`](https://github.com/shridarpatil/whatomate/tree/main/internal/websocket) (WebSocket)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_cmd_whatomate["whatomate<br/>Go entrypoint<br/>[main.go]"]
  node_server_mode(("Server mode<br/>HTTP runtime"))
  node_worker_mode(("Worker mode<br/>Job runtime"))
end

subgraph group_backend["Backend"]
  node_handlers["Handlers<br/>HTTP/API layer"]
  node_middleware["Middleware<br/>cross-cutting"]
  node_models["Models<br/>domain types"]
  node_authz{{"Governance<br/>multi-tenant access<br/>[organization.go]"}}
  node_chatbot{{"Chatbot<br/>automation<br/>[chatbot.go]"}}
  node_calling{{"Calling<br/>voice subsystem"}}
  node_websocket["WebSocket<br/>realtime hub"]
  node_queue["Queue<br/>async coordination"]
  node_worker["Worker<br/>background jobs"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["SPA<br/>Vue frontend"]
  node_flow_ui["Flow UI<br/>builder UI"]
  node_settings_ui["Settings<br/>admin UI"]
end

subgraph group_integrations["Integrations"]
  node_database["Database<br/>persistence"]
  node_storage["Storage"]
  node_whatsapp["WhatsApp<br/>provider SDK"]
end

subgraph group_ops["Ops"]
  node_embedded_frontend[("Embedded assets<br/>build output")]
  node_docs["Docs site<br/>Astro docs"]
  node_docker["Docker<br/>deployment packaging"]
end

node_cmd_whatomate -->|"selects"| node_server_mode
node_cmd_whatomate -->|"selects"| node_worker_mode
node_server_mode -->|"routes to"| node_handlers
node_server_mode -->|"wraps with"| node_middleware
node_handlers -->|"uses"| node_models
node_handlers -->|"manages"| node_authz
node_handlers -->|"orchestrates"| node_chatbot
node_handlers -->|"orchestrates"| node_calling
node_handlers -->|"publishes"| node_websocket
node_handlers -->|"enqueues"| node_queue
node_handlers -->|"persists via"| node_database
node_handlers -->|"stores media"| node_storage
node_handlers -->|"calls provider"| node_whatsapp
node_chatbot -->|"dispatches"| node_queue
node_chatbot -->|"streams"| node_websocket
node_calling -->|"coordinates"| node_queue
node_calling -->|"signals"| node_websocket
node_worker_mode -->|"runs"| node_worker
node_worker -->|"consumes"| node_queue
node_worker -->|"updates"| node_database
node_worker -->|"delivers via"| node_whatsapp
node_frontend_app -->|"includes"| node_flow_ui
node_frontend_app -->|"includes"| node_settings_ui
node_frontend_app -->|"connects to"| node_websocket
node_frontend_app -->|"builds into"| node_embedded_frontend
node_docs -.->|"documents"| node_handlers
node_docker -->|"packages"| node_cmd_whatomate
node_docker -->|"ships"| node_embedded_frontend

click node_cmd_whatomate "https://github.com/shridarpatil/whatomate/blob/main/cmd/whatomate/main.go"
click node_handlers "https://github.com/shridarpatil/whatomate/tree/main/internal/handlers"
click node_middleware "https://github.com/shridarpatil/whatomate/tree/main/internal/middleware"
click node_models "https://github.com/shridarpatil/whatomate/tree/main/internal/models"
click node_authz "https://github.com/shridarpatil/whatomate/blob/main/internal/handlers/organization.go"
click node_chatbot "https://github.com/shridarpatil/whatomate/blob/main/internal/handlers/chatbot.go"
click node_calling "https://github.com/shridarpatil/whatomate/tree/main/internal/calling"
click node_websocket "https://github.com/shridarpatil/whatomate/tree/main/internal/websocket"
click node_queue "https://github.com/shridarpatil/whatomate/tree/main/internal/queue"
click node_worker "https://github.com/shridarpatil/whatomate/tree/main/internal/worker"
click node_database "https://github.com/shridarpatil/whatomate/tree/main/internal/database"
click node_storage "https://github.com/shridarpatil/whatomate/tree/main/internal/storage"
click node_whatsapp "https://github.com/shridarpatil/whatomate/tree/main/pkg/whatsapp"
click node_frontend_app "https://github.com/shridarpatil/whatomate/tree/main/frontend/src"
click node_flow_ui "https://github.com/shridarpatil/whatomate/tree/main/frontend/src/components"
click node_settings_ui "https://github.com/shridarpatil/whatomate/tree/main/frontend/src/views/settings"
click node_embedded_frontend "https://github.com/shridarpatil/whatomate/tree/main/internal/frontend/dist"
click node_docs "https://github.com/shridarpatil/whatomate/tree/main/docs"
click node_docker "https://github.com/shridarpatil/whatomate/tree/main/docker"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmd_whatomate,node_server_mode,node_worker_mode toneBlue
class node_handlers,node_middleware,node_models,node_authz,node_chatbot,node_calling,node_websocket,node_queue,node_worker toneAmber
class node_frontend_app,node_flow_ui,node_settings_ui toneMint
class node_database,node_storage,node_whatsapp toneRose
class node_embedded_frontend,node_docs,node_docker toneIndigo
```

## Components

### Runtime

Executable modes and process boundary

- [whatomate](https://github.com/shridarpatil/whatomate/blob/main/cmd/whatomate/main.go): Go entrypoint · Main binary with server, worker, and version modes · `cmd/whatomate/main.go`
- **Server mode**: HTTP runtime · Runs API, websocket, and embedded frontend delivery
- **Worker mode**: Job runtime · Runs background processing without serving requests

### Backend

Go application core and domain services

- [Handlers](https://github.com/shridarpatil/whatomate/tree/main/internal/handlers): HTTP/API layer · Resource endpoints for auth, orgs, users, chat, campaigns, calling, and settings · `internal/handlers`
- [Middleware](https://github.com/shridarpatil/whatomate/tree/main/internal/middleware): cross-cutting · CSRF and rate limiting before handlers · `internal/middleware`
- [Models](https://github.com/shridarpatil/whatomate/tree/main/internal/models): domain types · Shared business entities and value types · `internal/models`
- [Governance](https://github.com/shridarpatil/whatomate/blob/main/internal/handlers/organization.go): multi-tenant access · Organizations, roles, teams, permissions, and scoped access control · `internal/handlers/organization.go`
- [Chatbot](https://github.com/shridarpatil/whatomate/blob/main/internal/handlers/chatbot.go): automation · Flow processing, keywords, AI contexts, transfers, and preview/simulation · `internal/handlers/chatbot.go`
- [Calling](https://github.com/shridarpatil/whatomate/tree/main/internal/calling): voice subsystem · IVR, transfers, outgoing calls, audio, DTMF, recordings, and WebRTC · `internal/calling`
- [WebSocket](https://github.com/shridarpatil/whatomate/tree/main/internal/websocket): realtime hub · Live agent/chat/call delivery and client fanout · `internal/websocket`
- [Queue](https://github.com/shridarpatil/whatomate/tree/main/internal/queue): async coordination · Pub/sub and queue primitives for deferred work · `internal/queue`
- [Worker](https://github.com/shridarpatil/whatomate/tree/main/internal/worker): background jobs · Campaign fanout, retries, webhooks, SLA processing, and other async tasks · `internal/worker`

### Frontend

Vue SPA and client-side state

- [SPA](https://github.com/shridarpatil/whatomate/tree/main/frontend/src): Vue frontend · Vue 3 application with router, stores, services, and feature views · `frontend/src`
- [Flow UI](https://github.com/shridarpatil/whatomate/tree/main/frontend/src/components): builder UI · Chatbot and calling flow editors plus previews and simulation tools · `frontend/src/components`
- [Settings](https://github.com/shridarpatil/whatomate/tree/main/frontend/src/views/settings): admin UI · Tenant, user, role, team, API key, webhook, and profile management screens · `frontend/src/views/settings`

### Integrations

External providers and infra dependencies

- [Database](https://github.com/shridarpatil/whatomate/tree/main/internal/database): persistence · PostgreSQL and Redis access boundary · `internal/database`
- [Storage](https://github.com/shridarpatil/whatomate/tree/main/internal/storage): object storage · S3-backed media and file storage · `internal/storage`
- [WhatsApp](https://github.com/shridarpatil/whatomate/tree/main/pkg/whatsapp): provider SDK · Cloud API integration for messages, templates, flows, webhooks, calls, and analytics · `pkg/whatsapp`

### Ops

Packaging, docs, and delivery

- [Embedded assets](https://github.com/shridarpatil/whatomate/tree/main/internal/frontend/dist): build output · Compiled frontend bundled into the Go binary for production · `internal/frontend/dist`
- [Docs site](https://github.com/shridarpatil/whatomate/tree/main/docs): Astro docs · Standalone documentation site and API reference · `docs`
- [Docker](https://github.com/shridarpatil/whatomate/tree/main/docker): deployment packaging · Container builds, compose stack, and release image definitions · `docker`

## Connections

- whatomate → Server mode: selects · Launches the HTTP-serving runtime
- whatomate → Worker mode: selects · Launches the background-job runtime
- Server mode → Handlers: routes to · Serves API requests through the handler layer
- Server mode → Middleware: wraps with · Applies shared request policy before handlers
- Handlers → Models: uses · Maps request handling onto shared domain entities
- Handlers → Governance: manages · Exposes tenant and permission administration
- Handlers → Chatbot: orchestrates · Creates, executes, and previews automation flows
- Handlers → Calling: orchestrates · Exposes calling and IVR operations
- Handlers → WebSocket: publishes · Pushes live updates to connected clients
- Handlers → Queue: enqueues · Defers work into async coordination paths
- Handlers → Database: persists via · Reads and writes durable application state
- Handlers → Storage: stores media · Uploads and retrieves files and recordings
- Handlers → WhatsApp: calls provider · Uses the WhatsApp Cloud API integration
- Chatbot → Queue: dispatches · Uses queued work for downstream processing
- Chatbot → WebSocket: streams · Surfaces live flow and chat activity
- Calling → Queue: coordinates · Uses transient state and async call workflows
- Calling → WebSocket: signals · Broadcasts call state and agent events
- Worker mode → Worker: runs · Executes background processors
- Worker → Queue: consumes · Polls or subscribes to queued jobs
- Worker → Database: updates · Writes job side effects to durable storage
- Worker → WhatsApp: delivers via · Sends messages and integration callbacks
- SPA → Flow UI: includes · Provides feature views and editors for automation flows
- SPA → Settings: includes · Provides administrative screens for tenant governance
- SPA → WebSocket: connects to · Consumes realtime updates from the backend
- SPA → Embedded assets: builds into · Production assets are compiled for embedding
- Docs site → Handlers: documents · Covers API and feature contracts exposed by the backend
- Docker → whatomate: packages · Builds and runs the Go binary in containers
- Docker → Embedded assets: ships · Includes compiled frontend assets in release images