# th3saquib/wato architecture

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

- Interactive diagram: https://gitdiagram.com/th3saquib/wato
- Repository: https://github.com/th3saquib/wato

## Overview

#### Purpose and Entry Points
wacrm is a self-hosted, account-scoped WhatsApp CRM: shared inbox, contacts, pipelines, broadcasts, visual automations/flows, AI assistance, and public integrations. The primary runtime is a Next.js App Router application rooted at `src/app/layout.tsx`, with authentication/dashboard route groups in `src/app/(auth)` and `src/app/(dashboard)`. HTTP integration entry points are Next route handlers under `src/app/api`, notably WhatsApp webhooks and the versioned REST API.

#### Application Shell, Identity, and Tenancy
Supabase Auth establishes user identity; middleware protects navigation and redirects unauthenticated users. Account membership, roles, invitations, ownership, and scoped API access form the core multi-user boundary. Database RLS is the principal data-isolation mechanism.
- `src/middleware.ts`
- `src/lib/auth/api-context.ts`
- `src/app/api/account/members/route.ts`
- `supabase/migrations/017_account_sharing.sql`

#### CRM Workspace and Realtime Inbox
Dashboard pages compose client-facing CRM modules: inbox, contacts, pipelines, activity, notifications, and settings. Inbox operations resolve WhatsApp messages to conversations and contacts; browser-side realtime/presence hooks keep shared-agent views current.
- `src/app/(dashboard)/inbox/page.tsx`
- `src/components/inbox/message-thread.tsx`
- `src/lib/inbox/conversations.ts`
- `src/hooks/use-realtime.ts`

#### WhatsApp Boundary
The Meta Cloud API is isolated behind WhatsApp library code and route handlers. Outbound sends, reactions, media, template lifecycle, broadcast delivery, registration/configuration, and inbound webhook verification are handled at this boundary. Credentials/tokens require encryption, while inbound public webhooks require signature verification.
- `src/app/api/whatsapp/webhook/route.ts`
- `src/lib/whatsapp/meta-api.ts`
- `src/lib/whatsapp/send-message.ts`
- `src/lib/whatsapp/encryption.ts`

#### Campaigns, Automations, and Flows
Broadcasts use approved templates, recipient selection/personalization, scheduling, and status tracking. Automations and flows are separately modeled visual execution systems: API routes invoke validation and engines; cron endpoints advance scheduled or waiting work; actions can send through Meta and trigger webhooks.
- `src/lib/automations/engine.ts`
- `src/app/api/automations/cron/route.ts`
- `src/lib/flows/engine.ts`
- `src/app/api/flows/cron/route.ts`
- `src/components/flows/flow-builder.tsx`

#### AI Assistance and Knowledge Retrieval
AI features support generated drafts, constrained auto-replies with human handoff, usage tracking, and account-managed knowledge. Providers are OpenAI and Anthropic; retrieval uses Postgres full-text search and optionally pgvector embeddings. AI configuration and keys are administrative/account-scoped.
- `src/app/api/ai/autoreply/[conversationId]/route.ts`
- `src/lib/ai/auto-reply.ts`
- `src/lib/ai/query.ts`
- `src/lib/ai/providers/openai.ts`

#### External API, MCP, and Event Delivery
`/api/v1` exposes authenticated CRM resources using scoped, revocable API keys. Registered outbound webhooks deliver signed events with SSRF protections. A distinct Node/TypeScript MCP server connects AI clients to this public API, defaulting to read-only operations with explicit write tooling.
- `src/app/api/v1/contacts/route.ts`
- `src/lib/api-keys/keys.ts`
- `src/lib/webhooks/deliver.ts`
- `mcp-server/src/index.ts`

#### Persistence and Deployment
Supabase provides Postgres, Auth, Storage, Realtime, RPCs, and RLS; migrations are the authoritative schema evolution path. The app runs on Node.js/Next.js and can deploy to Hostinger or other Node hosts. Meta Cloud API, Supabase, and optional OpenAI/Anthropic services are required material external dependencies.
- `src/lib/supabase/server.ts`
- `src/lib/storage/upload-media.ts`
- `supabase/migrations/001_initial_schema.sql`
- `supabase/migrations/010_flows.sql`

Main entry points: [`src/lib/inbox/conversations.ts`](https://github.com/th3saquib/wato/blob/main/src/lib/inbox/conversations.ts) (Conversation service), [`src/lib/whatsapp/send-message.ts`](https://github.com/th3saquib/wato/blob/main/src/lib/whatsapp/send-message.ts) (Message sender), [`src/lib/supabase/server.ts`](https://github.com/th3saquib/wato/blob/main/src/lib/supabase/server.ts) (Supabase platform), [`src/app/layout.tsx`](https://github.com/th3saquib/wato/blob/main/src/app/layout.tsx) (App shell & routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Next.js application"]
  node_shell["App shell &amp; routes<br/>Next.js App Router<br/>[layout.tsx]"]
  node_middleware["Auth middleware<br/>Next middleware<br/>[middleware.ts]"]
  node_api_context["Scoped API identity<br/>auth context<br/>[api-context.ts]"]
end

subgraph group_crm["CRM workspace"]
  node_inbox["Shared inbox<br/>CRM module<br/>[page.tsx]"]
  node_message_thread["Message thread<br/>client component<br/>[message-thread.tsx]"]
  node_conversations["Conversation service<br/>inbox domain service<br/>[conversations.ts]"]
  node_realtime["Realtime presence<br/>browser hook<br/>[use-realtime.ts]"]
end

subgraph group_automation["Automation systems"]
  node_automations["Automation engine<br/>execution engine<br/>[engine.ts]"]
  node_automation_cron["Automation scheduler<br/>cron route handler<br/>[route.ts]"]
  node_flows["Flow engine<br/>execution engine<br/>[engine.ts]"]
  node_flow_builder["Flow builder<br/>visual editor<br/>[flow-builder.tsx]"]
  node_ai_autoreply["AI auto-reply<br/>AI service<br/>[auto-reply.ts]"]
end

subgraph group_integration["Integration boundary"]
  node_whatsapp_webhook{{"WhatsApp webhook<br/>public route handler<br/>[route.ts]"}}
  node_meta_api["Meta Cloud gateway<br/>WhatsApp API client<br/>[meta-api.ts]"]
  node_message_sender["Message sender<br/>WhatsApp service<br/>[send-message.ts]"]
  node_public_api{{"Versioned REST API<br/>authenticated route handler<br/>[route.ts]"}}
  node_api_keys["Revocable API keys<br/>credential service<br/>[keys.ts]"]
  node_event_delivery["Outbound webhooks<br/>event delivery service<br/>[deliver.ts]"]
  node_mcp["MCP server<br/>Node.js server<br/>[index.ts]"]
end

subgraph group_platform["Platform services"]
  node_tenancy[("Accounts &amp; RLS<br/>Postgres policy schema")]
  node_supabase[("Supabase platform<br/>Postgres, Auth, Storage, Realtime<br/>[server.ts]")]
  node_media_storage["Media upload<br/>storage service<br/>[upload-media.ts]"]
  node_schema["Core schema<br/>database migration"]
end

node_meta{{"Meta Cloud API<br/>external service"}}
node_ai_providers{{"OpenAI &amp; Anthropic<br/>external AI providers"}}

node_middleware -->|"guards routes"| node_shell
node_shell -->|"renders"| node_inbox
node_shell -->|"serves APIs with"| node_api_context
node_api_context -->|"enforces account scope"| node_tenancy
node_tenancy -->|"RLS policies on"| node_supabase
node_schema -->|"defines schema"| node_supabase
node_inbox -->|"composes"| node_message_thread
node_message_thread -->|"uses"| node_conversations
node_inbox -->|"subscribes through"| node_realtime
node_conversations -->|"reads and writes"| node_supabase
node_whatsapp_webhook -->|"ingests inbound messages"| node_conversations
node_message_sender -->|"uses"| node_meta_api
node_meta_api -->|"calls"| node_meta
node_automations -->|"sends actions through"| node_message_sender
node_automation_cron -->|"advances"| node_automations
node_flow_builder -->|"defines"| node_flows
node_flows -->|"sends actions through"| node_message_sender
node_ai_autoreply -->|"generates with"| node_ai_providers
node_ai_autoreply -->|"uses conversation context"| node_conversations
node_public_api -->|"authenticates with"| node_api_keys
node_public_api -->|"accesses CRM resources"| node_conversations
node_mcp -->|"uses"| node_public_api
node_event_delivery -->|"reads event data"| node_supabase
node_message_sender -.->|"uploads media through"| node_media_storage

click node_shell "https://github.com/th3saquib/wato/blob/main/src/app/layout.tsx"
click node_middleware "https://github.com/th3saquib/wato/blob/main/src/middleware.ts"
click node_api_context "https://github.com/th3saquib/wato/blob/main/src/lib/auth/api-context.ts"
click node_tenancy "https://github.com/th3saquib/wato/blob/main/supabase/migrations/017_account_sharing.sql"
click node_inbox "https://github.com/th3saquib/wato/blob/main/src/app/(dashboard)/inbox/page.tsx"
click node_message_thread "https://github.com/th3saquib/wato/blob/main/src/components/inbox/message-thread.tsx"
click node_conversations "https://github.com/th3saquib/wato/blob/main/src/lib/inbox/conversations.ts"
click node_realtime "https://github.com/th3saquib/wato/blob/main/src/hooks/use-realtime.ts"
click node_whatsapp_webhook "https://github.com/th3saquib/wato/blob/main/src/app/api/whatsapp/webhook/route.ts"
click node_meta_api "https://github.com/th3saquib/wato/blob/main/src/lib/whatsapp/meta-api.ts"
click node_message_sender "https://github.com/th3saquib/wato/blob/main/src/lib/whatsapp/send-message.ts"
click node_automations "https://github.com/th3saquib/wato/blob/main/src/lib/automations/engine.ts"
click node_automation_cron "https://github.com/th3saquib/wato/blob/main/src/app/api/automations/cron/route.ts"
click node_flows "https://github.com/th3saquib/wato/blob/main/src/lib/flows/engine.ts"
click node_flow_builder "https://github.com/th3saquib/wato/blob/main/src/components/flows/flow-builder.tsx"
click node_ai_autoreply "https://github.com/th3saquib/wato/blob/main/src/lib/ai/auto-reply.ts"
click node_public_api "https://github.com/th3saquib/wato/blob/main/src/app/api/v1/contacts/route.ts"
click node_api_keys "https://github.com/th3saquib/wato/blob/main/src/lib/api-keys/keys.ts"
click node_event_delivery "https://github.com/th3saquib/wato/blob/main/src/lib/webhooks/deliver.ts"
click node_mcp "https://github.com/th3saquib/wato/blob/main/mcp-server/src/index.ts"
click node_supabase "https://github.com/th3saquib/wato/blob/main/src/lib/supabase/server.ts"
click node_media_storage "https://github.com/th3saquib/wato/blob/main/src/lib/storage/upload-media.ts"
click node_schema "https://github.com/th3saquib/wato/blob/main/supabase/migrations/001_initial_schema.sql"

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_shell,node_middleware,node_api_context toneBlue
class node_inbox,node_message_thread,node_conversations,node_realtime toneAmber
class node_automations,node_automation_cron,node_flows,node_flow_builder,node_ai_autoreply toneMint
class node_whatsapp_webhook,node_meta_api,node_message_sender,node_public_api,node_api_keys,node_event_delivery,node_mcp toneRose
class node_tenancy,node_supabase,node_media_storage,node_schema toneIndigo
class node_meta,node_ai_providers toneNeutral
```

## Components

### Next.js application

- [App shell & routes](https://github.com/th3saquib/wato/blob/main/src/app/layout.tsx): Next.js App Router · Hosts authenticated dashboard and HTTP route handlers. · `src/app/layout.tsx`
- [Auth middleware](https://github.com/th3saquib/wato/blob/main/src/middleware.ts): Next middleware · Protects navigation and redirects unauthenticated users. · `src/middleware.ts`
- [Scoped API identity](https://github.com/th3saquib/wato/blob/main/src/lib/auth/api-context.ts): auth context · Resolves account-scoped API access. · `src/lib/auth/api-context.ts`

### CRM workspace

- [Shared inbox](https://github.com/th3saquib/wato/blob/main/src/app/(dashboard)/inbox/page.tsx): CRM module · Conversation and contact workspace for agents. · `src/app/(dashboard)/inbox/page.tsx`
- [Message thread](https://github.com/th3saquib/wato/blob/main/src/components/inbox/message-thread.tsx): client component · Renders and operates on a conversation. · `src/components/inbox/message-thread.tsx`
- [Conversation service](https://github.com/th3saquib/wato/blob/main/src/lib/inbox/conversations.ts): inbox domain service · Resolves messages to conversations and contacts. · `src/lib/inbox/conversations.ts`
- [Realtime presence](https://github.com/th3saquib/wato/blob/main/src/hooks/use-realtime.ts): browser hook · Keeps shared-agent inbox views current. · `src/hooks/use-realtime.ts`

### Automation systems

- [Automation engine](https://github.com/th3saquib/wato/blob/main/src/lib/automations/engine.ts): execution engine · Validates and executes visual automations. · `src/lib/automations/engine.ts`
- [Automation scheduler](https://github.com/th3saquib/wato/blob/main/src/app/api/automations/cron/route.ts): cron route handler · Advances scheduled and waiting automation work. · `src/app/api/automations/cron/route.ts`
- [Flow engine](https://github.com/th3saquib/wato/blob/main/src/lib/flows/engine.ts): execution engine · Executes visual flow definitions and actions. · `src/lib/flows/engine.ts`
- [Flow builder](https://github.com/th3saquib/wato/blob/main/src/components/flows/flow-builder.tsx): visual editor · Creates and edits flow definitions. · `src/components/flows/flow-builder.tsx`
- [AI auto-reply](https://github.com/th3saquib/wato/blob/main/src/lib/ai/auto-reply.ts): AI service · Creates constrained replies with human handoff. · `src/lib/ai/auto-reply.ts`

### Integration boundary

- [WhatsApp webhook](https://github.com/th3saquib/wato/blob/main/src/app/api/whatsapp/webhook/route.ts): public route handler · Verifies inbound Meta webhooks. · `src/app/api/whatsapp/webhook/route.ts`
- [Meta Cloud gateway](https://github.com/th3saquib/wato/blob/main/src/lib/whatsapp/meta-api.ts): WhatsApp API client · Handles outbound messaging and WhatsApp operations. · `src/lib/whatsapp/meta-api.ts`
- [Message sender](https://github.com/th3saquib/wato/blob/main/src/lib/whatsapp/send-message.ts): WhatsApp service · Sends outbound messages through Meta. · `src/lib/whatsapp/send-message.ts`
- [Versioned REST API](https://github.com/th3saquib/wato/blob/main/src/app/api/v1/contacts/route.ts): authenticated route handler · Exposes scoped CRM resources to integrations. · `src/app/api/v1/contacts/route.ts`
- [Revocable API keys](https://github.com/th3saquib/wato/blob/main/src/lib/api-keys/keys.ts): credential service · Authenticates external API clients. · `src/lib/api-keys/keys.ts`
- [Outbound webhooks](https://github.com/th3saquib/wato/blob/main/src/lib/webhooks/deliver.ts): event delivery service · Signs deliveries and protects against SSRF. · `src/lib/webhooks/deliver.ts`
- [MCP server](https://github.com/th3saquib/wato/blob/main/mcp-server/src/index.ts): Node.js server · Provides read-first AI-client access to the public API. · `mcp-server/src/index.ts`

### Platform services

- [Accounts & RLS](https://github.com/th3saquib/wato/blob/main/supabase/migrations/017_account_sharing.sql): Postgres policy schema · Membership, roles, invitations, and account isolation. · `supabase/migrations/017_account_sharing.sql`
- [Supabase platform](https://github.com/th3saquib/wato/blob/main/src/lib/supabase/server.ts): Postgres, Auth, Storage, Realtime · Provides persistence, identity, storage, RPCs, and realtime. · `src/lib/supabase/server.ts`
- [Media upload](https://github.com/th3saquib/wato/blob/main/src/lib/storage/upload-media.ts): storage service · Stores media through Supabase Storage. · `src/lib/storage/upload-media.ts`
- [Core schema](https://github.com/th3saquib/wato/blob/main/supabase/migrations/001_initial_schema.sql): database migration · Authoritative baseline schema evolution. · `supabase/migrations/001_initial_schema.sql`

### Other components

- **Meta Cloud API**: external service
- **OpenAI & Anthropic**: external AI providers

## Connections

- Auth middleware → App shell & routes: guards routes
- App shell & routes → Shared inbox: renders
- App shell & routes → Scoped API identity: serves APIs with
- Scoped API identity → Accounts & RLS: enforces account scope
- Accounts & RLS → Supabase platform: RLS policies on
- Core schema → Supabase platform: defines schema
- Shared inbox → Message thread: composes
- Message thread → Conversation service: uses
- Shared inbox → Realtime presence: subscribes through
- Conversation service → Supabase platform: reads and writes
- WhatsApp webhook → Conversation service: ingests inbound messages
- Message sender → Meta Cloud gateway: uses
- Meta Cloud gateway → Meta Cloud API: calls
- Automation engine → Message sender: sends actions through
- Automation scheduler → Automation engine: advances
- Flow builder → Flow engine: defines
- Flow engine → Message sender: sends actions through
- AI auto-reply → OpenAI & Anthropic: generates with
- AI auto-reply → Conversation service: uses conversation context
- Versioned REST API → Revocable API keys: authenticates with
- Versioned REST API → Conversation service: accesses CRM resources
- MCP server → Versioned REST API: uses
- Outbound webhooks → Supabase platform: reads event data
- Message sender → Media upload: uploads media through