shridarpatil/whatomate

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.