# trulytuhin/almanac-crm architecture

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

- Interactive diagram: https://gitdiagram.com/trulytuhin/almanac-crm
- Repository: https://github.com/trulytuhin/almanac-crm

## Overview

Almanac is a self-hosted WhatsApp CRM: Meta delivers inbound messages to its webhook, which records customer conversations and dispatches automation, flow and AI behavior; staff then work shared inboxes, contacts and deals, or initiate template broadcasts. The Next.js app exposes dashboard workflows and APIs, with Supabase providing persistence, auth and realtime. Major capabilities not sampled are represented from the README; their precise internal wiring is therefore not asserted. Source excerpts support the webhook dispatch and selected engine/helper relationships.

Main entry points: [`src/app/api/whatsapp/webhook/route.ts`](https://github.com/trulytuhin/almanac-crm/blob/main/src/app/api/whatsapp/webhook/route.ts) (Inbound webhook), [`src/app/(dashboard)`](https://github.com/trulytuhin/almanac-crm/tree/main/src/app/(dashboard)) (CRM dashboard), [`src/lib/supabase/server.ts`](https://github.com/trulytuhin/almanac-crm/blob/main/src/lib/supabase/server.ts) (Supabase data services), [`src/lib/automations/engine.ts`](https://github.com/trulytuhin/almanac-crm/blob/main/src/lib/automations/engine.ts) (Automation engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["CRM experience"]
  node_dashboard["CRM dashboard"]
  node_inbox["Shared inbox<br/>[page.tsx]"]
  node_contacts["Contact management<br/>[page.tsx]"]
  node_pipelines["Sales pipelines<br/>[page.tsx]"]
  node_broadcasts["Broadcast workflow"]
  node_api["REST API"]
  node_mcp["MCP tools"]
end

subgraph group_messaging["WhatsApp messaging"]
  node_webhook["Inbound webhook<br/>[route.ts]"]
  node_send["WhatsApp send<br/>[send-message.ts]"]
  node_metaapi["Meta API client<br/>[meta-api.ts]"]
  node_template["Template management"]
  node_broadcastsend["Broadcast delivery<br/>[route.ts]"]
end

subgraph group_orchestration["Conversation automation"]
  node_automation["Automation engine<br/>[engine.ts]"]
  node_flows["Chatbot flow engine<br/>[engine.ts]"]
  node_ai["AI replies<br/>[auto-reply.ts]"]
  node_webhooks["Signed webhooks<br/>[deliver.ts]"]
end

subgraph group_platform["Account platform"]
  node_account["Account authorization<br/>[account.ts]"]
  node_authhook["Browser auth state<br/>[use-auth.tsx]"]
  node_supabase[("Supabase data services<br/>[server.ts]")]
  node_encryption["Token encryption<br/>[encryption.ts]"]
end

subgraph group_integrations["External integrations"]
  node_meta{{"WhatsApp Business Platform"}}
  node_llm{{"OpenAI / Anthropic"}}
end

node_operator(("Business staff"))
node_staff(("AI / API clients"))

node_operator -->|"uses"| node_dashboard
node_dashboard -->|"opens"| node_inbox
node_dashboard -->|"manages"| node_contacts
node_dashboard -->|"tracks deals"| node_pipelines
node_dashboard -->|"creates sends"| node_broadcasts
node_staff -->|"calls"| node_api
node_staff -->|"uses"| node_mcp
node_meta -->|"delivers events"| node_webhook
node_webhook -->|"dispatches triggers"| node_automation
node_webhook -->|"dispatches messages"| node_flows
node_webhook -->|"invokes replies"| node_ai
node_webhook -->|"dispatches events"| node_webhooks
node_automation -->|"sends messages"| node_send
node_flows -->|"sends messages"| node_send
node_automation -->|"reads and writes"| node_supabase
node_flows -->|"reads and writes"| node_supabase
node_send -.->|"uses client"| node_metaapi
node_metaapi -->|"calls API"| node_meta
node_broadcasts -->|"submits campaign"| node_broadcastsend
node_broadcastsend -->|"sends templates"| node_metaapi
node_template -->|"manages approved templates"| node_meta
node_ai -->|"requests generation"| node_llm
node_account -->|"loads account"| node_supabase
node_authhook -->|"authenticates"| node_supabase
node_webhook -->|"decrypts tokens"| node_encryption
node_api -.->|"authorizes requests"| node_account
node_mcp -.->|"accesses CRM"| node_api

click node_dashboard "https://github.com/trulytuhin/almanac-crm/tree/main/src/app/(dashboard)"
click node_inbox "https://github.com/trulytuhin/almanac-crm/blob/main/src/app/(dashboard)/inbox/page.tsx"
click node_contacts "https://github.com/trulytuhin/almanac-crm/blob/main/src/app/(dashboard)/contacts/page.tsx"
click node_pipelines "https://github.com/trulytuhin/almanac-crm/blob/main/src/app/(dashboard)/pipelines/page.tsx"
click node_broadcasts "https://github.com/trulytuhin/almanac-crm/tree/main/src/app/(dashboard)/broadcasts"
click node_api "https://github.com/trulytuhin/almanac-crm/tree/main/src/app/api/v1"
click node_mcp "https://github.com/trulytuhin/almanac-crm/tree/main/mcp-server/src/tools"
click node_webhook "https://github.com/trulytuhin/almanac-crm/blob/main/src/app/api/whatsapp/webhook/route.ts"
click node_send "https://github.com/trulytuhin/almanac-crm/blob/main/src/lib/whatsapp/send-message.ts"
click node_metaapi "https://github.com/trulytuhin/almanac-crm/blob/main/src/lib/whatsapp/meta-api.ts"
click node_template "https://github.com/trulytuhin/almanac-crm/blob/main/src/components/settings/template-manager.tsx"
click node_broadcastsend "https://github.com/trulytuhin/almanac-crm/blob/main/src/app/api/whatsapp/broadcast/route.ts"
click node_automation "https://github.com/trulytuhin/almanac-crm/blob/main/src/lib/automations/engine.ts"
click node_flows "https://github.com/trulytuhin/almanac-crm/blob/main/src/lib/flows/engine.ts"
click node_ai "https://github.com/trulytuhin/almanac-crm/blob/main/src/lib/ai/auto-reply.ts"
click node_webhooks "https://github.com/trulytuhin/almanac-crm/blob/main/src/lib/webhooks/deliver.ts"
click node_account "https://github.com/trulytuhin/almanac-crm/blob/main/src/lib/auth/account.ts"
click node_authhook "https://github.com/trulytuhin/almanac-crm/blob/main/src/hooks/use-auth.tsx"
click node_supabase "https://github.com/trulytuhin/almanac-crm/blob/main/src/lib/supabase/server.ts"
click node_encryption "https://github.com/trulytuhin/almanac-crm/blob/main/src/lib/whatsapp/encryption.ts"

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_dashboard,node_inbox,node_contacts,node_pipelines,node_broadcasts,node_api,node_mcp,node_staff toneBlue
class node_webhook,node_send,node_metaapi,node_template,node_broadcastsend toneAmber
class node_automation,node_flows,node_ai,node_webhooks toneMint
class node_account,node_authhook,node_supabase,node_encryption toneRose
class node_meta,node_llm,node_operator toneIndigo
```

## Components

### CRM experience

- [CRM dashboard](https://github.com/trulytuhin/almanac-crm/tree/main/src/app/(dashboard)): `src/app/(dashboard)`
- [Shared inbox](https://github.com/trulytuhin/almanac-crm/blob/main/src/app/(dashboard)/inbox/page.tsx): `src/app/(dashboard)/inbox/page.tsx`
- [Contact management](https://github.com/trulytuhin/almanac-crm/blob/main/src/app/(dashboard)/contacts/page.tsx): `src/app/(dashboard)/contacts/page.tsx`
- [Sales pipelines](https://github.com/trulytuhin/almanac-crm/blob/main/src/app/(dashboard)/pipelines/page.tsx): `src/app/(dashboard)/pipelines/page.tsx`
- [Broadcast workflow](https://github.com/trulytuhin/almanac-crm/tree/main/src/app/(dashboard)/broadcasts): `src/app/(dashboard)/broadcasts`
- [REST API](https://github.com/trulytuhin/almanac-crm/tree/main/src/app/api/v1): `src/app/api/v1`
- [MCP tools](https://github.com/trulytuhin/almanac-crm/tree/main/mcp-server/src/tools): `mcp-server/src/tools`

### WhatsApp messaging

- [Inbound webhook](https://github.com/trulytuhin/almanac-crm/blob/main/src/app/api/whatsapp/webhook/route.ts): `src/app/api/whatsapp/webhook/route.ts`
- [WhatsApp send](https://github.com/trulytuhin/almanac-crm/blob/main/src/lib/whatsapp/send-message.ts): `src/lib/whatsapp/send-message.ts`
- [Meta API client](https://github.com/trulytuhin/almanac-crm/blob/main/src/lib/whatsapp/meta-api.ts): `src/lib/whatsapp/meta-api.ts`
- [Template management](https://github.com/trulytuhin/almanac-crm/blob/main/src/components/settings/template-manager.tsx): `src/components/settings/template-manager.tsx`
- [Broadcast delivery](https://github.com/trulytuhin/almanac-crm/blob/main/src/app/api/whatsapp/broadcast/route.ts): `src/app/api/whatsapp/broadcast/route.ts`

### Conversation automation

- [Automation engine](https://github.com/trulytuhin/almanac-crm/blob/main/src/lib/automations/engine.ts): `src/lib/automations/engine.ts`
- [Chatbot flow engine](https://github.com/trulytuhin/almanac-crm/blob/main/src/lib/flows/engine.ts): `src/lib/flows/engine.ts`
- [AI replies](https://github.com/trulytuhin/almanac-crm/blob/main/src/lib/ai/auto-reply.ts): `src/lib/ai/auto-reply.ts`
- [Signed webhooks](https://github.com/trulytuhin/almanac-crm/blob/main/src/lib/webhooks/deliver.ts): `src/lib/webhooks/deliver.ts`

### Account platform

- [Account authorization](https://github.com/trulytuhin/almanac-crm/blob/main/src/lib/auth/account.ts): `src/lib/auth/account.ts`
- [Browser auth state](https://github.com/trulytuhin/almanac-crm/blob/main/src/hooks/use-auth.tsx): `src/hooks/use-auth.tsx`
- [Supabase data services](https://github.com/trulytuhin/almanac-crm/blob/main/src/lib/supabase/server.ts): `src/lib/supabase/server.ts`
- [Token encryption](https://github.com/trulytuhin/almanac-crm/blob/main/src/lib/whatsapp/encryption.ts): `src/lib/whatsapp/encryption.ts`

### External integrations

- **WhatsApp Business Platform**
- **OpenAI / Anthropic**

### Other components

- **Business staff**
- **AI / API clients**

## Connections

- Business staff → CRM dashboard: uses (evidence: `README.md`)
- CRM dashboard → Shared inbox: opens (evidence: `README.md`)
- CRM dashboard → Contact management: manages (evidence: `README.md`)
- CRM dashboard → Sales pipelines: tracks deals (evidence: `README.md`)
- CRM dashboard → Broadcast workflow: creates sends (evidence: `README.md`)
- AI / API clients → REST API: calls (evidence: `README.md`)
- AI / API clients → MCP tools: uses (evidence: `README.md`)
- WhatsApp Business Platform → Inbound webhook: delivers events (evidence: `README.md`)
- Inbound webhook → Automation engine: dispatches triggers (evidence: `src/app/api/whatsapp/webhook/route.ts`)
- Inbound webhook → Chatbot flow engine: dispatches messages (evidence: `src/lib/flows/engine.ts`)
- Inbound webhook → AI replies: invokes replies (evidence: `src/app/api/whatsapp/webhook/route.ts`)
- Inbound webhook → Signed webhooks: dispatches events (evidence: `src/app/api/whatsapp/webhook/route.ts`)
- Automation engine → WhatsApp send: sends messages (evidence: `src/lib/automations/engine.ts`)
- Chatbot flow engine → WhatsApp send: sends messages (evidence: `src/lib/flows/engine.ts`)
- Automation engine → Supabase data services: reads and writes (evidence: `src/lib/automations/engine.ts`)
- Chatbot flow engine → Supabase data services: reads and writes (evidence: `src/lib/flows/engine.ts`)
- WhatsApp send → Meta API client: uses client
- Meta API client → WhatsApp Business Platform: calls API (evidence: `README.md`)
- Broadcast workflow → Broadcast delivery: submits campaign (evidence: `README.md`)
- Broadcast delivery → Meta API client: sends templates (evidence: `src/app/api/whatsapp/broadcast/route.ts`)
- Template management → WhatsApp Business Platform: manages approved templates (evidence: `README.md`)
- AI replies → OpenAI / Anthropic: requests generation (evidence: `README.md`)
- Account authorization → Supabase data services: loads account (evidence: `src/lib/auth/account.ts`)
- Browser auth state → Supabase data services: authenticates (evidence: `src/hooks/use-auth.tsx`)
- Inbound webhook → Token encryption: decrypts tokens (evidence: `src/app/api/whatsapp/webhook/route.ts`)
- REST API → Account authorization: authorizes requests
- MCP tools → REST API: accesses CRM
