# rafaelsantana6/zapo-rest architecture

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

- Interactive diagram: https://gitdiagram.com/rafaelsantana6/zapo-rest
- Repository: https://github.com/rafaelsantana6/zapo-rest

## Overview

zapo-rest is a multi-session WhatsApp REST gateway: clients authenticate and operate named WhatsApp instances, while the service manages sessions, exposes messaging and operational APIs, and projects WhatsApp activity into durable stores and live integrations. The main runtime path is HTTP request through the Fastify app and routes to instance management and WhatsApp clients; inbound events are processed into chat, contact, message, and identity projections before webhook delivery or SSE. Media storage, VoIP, the dashboard, and API documentation are distinct product capabilities. Some route and boot wiring is unsampled, so only documented or indexed relationships are shown.

Main entry points: [`src/events/processor.ts`](https://github.com/rafaelsantana6/zapo-rest/blob/main/src/events/processor.ts) (Event processor), [`src/routes`](https://github.com/rafaelsantana6/zapo-rest/tree/main/src/routes) (REST endpoints), [`src/app.ts`](https://github.com/rafaelsantana6/zapo-rest/blob/main/src/app.ts) (Fastify application), [`src/instances/manager.ts`](https://github.com/rafaelsantana6/zapo-rest/blob/main/src/instances/manager.ts) (Instance lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and interfaces"]
  node_app["Fastify application<br/>[app.ts]"]
  node_auth["API-key authentication<br/>[plugin.ts]"]
  node_api_routes["REST endpoints"]
end

subgraph group_sessions["Sessions and identity"]
  node_instance_manager["Instance lifecycle<br/>[manager.ts]"]
  node_instance_repo[("Instance records<br/>[repo.ts]")]
  node_wa_client["WhatsApp client<br/>[wa-client.ts]"]
end

subgraph group_events["Events and projections"]
  node_processor["Event processor<br/>[processor.ts]"]
  node_chat_store[("Chat projections<br/>[chats.ts]")]
  node_message_store[("Message history<br/>[messages.ts]")]
  node_contact_store[("Contact projections<br/>[contacts.ts]")]
  node_identity_map[("LID-to-PN mapping<br/>[lid-map.ts]")]
  node_postgres[("PostgreSQL")]
end

subgraph group_integrations["Media and integrations"]
  node_sse["Live event stream<br/>[events-sse.ts]"]
  node_webhooks["Webhook delivery<br/>[dispatcher.ts]"]
  node_webhook_outbox[("Webhook outbox<br/>[outbox.ts]")]
  node_media_api["Media endpoints<br/>[media.ts]"]
  node_media_storage["Media storage<br/>[storage.ts]"]
  node_object_store[("S3-compatible storage")]
  node_voip["VoIP control and audio<br/>[voip-ws.ts]"]
  node_call_recording["Call recording"]
  node_call_store[("Call records<br/>[calls.ts]")]
end

subgraph group_operator["Operator experience"]
  node_dashboard["Operations dashboard<br/>[App.tsx]"]
  node_dashboard_api["Dashboard API client<br/>[client.ts]"]
  node_softphone["Dashboard softphone<br/>[Softphone.tsx]"]
  node_docs["API guide and reference"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_app
node_app -->|"registers"| node_auth
node_app -->|"registers"| node_api_routes
node_api_routes -->|"uses sessions"| node_instance_manager
node_auth -->|"resolves keys"| node_instance_repo
node_instance_manager -->|"manages records"| node_instance_repo
node_instance_manager -->|"manages sessions"| node_wa_client
node_wa_client -.->|"emits events"| node_processor
node_processor -->|"upserts chats"| node_chat_store
node_processor -->|"projects messages"| node_message_store
node_processor -->|"updates contacts"| node_contact_store
node_processor -->|"records identity"| node_identity_map
node_chat_store -->|"reads and writes"| node_postgres
node_message_store -.->|"persists history"| node_postgres
node_contact_store -.->|"persists contacts"| node_postgres
node_identity_map -.->|"persists mappings"| node_postgres
node_processor -->|"dispatches events"| node_webhooks
node_webhooks -->|"queues delivery"| node_webhook_outbox
node_webhook_outbox -.->|"delivers retries"| node_client
node_processor -.->|"publishes events"| node_sse
node_api_routes -.->|"includes routes"| node_media_api
node_media_api -.->|"serves media"| node_media_storage
node_media_storage -.->|"stores objects"| node_object_store
node_api_routes -.->|"includes control"| node_voip
node_call_recording -->|"updates recordings"| node_call_store
node_call_recording -.->|"stores recordings"| node_media_storage
node_dashboard -->|"calls API"| node_dashboard_api
node_dashboard -->|"renders"| node_softphone
node_dashboard_api -.->|"calls REST API"| node_app
node_docs -.->|"documents API"| node_client

click node_app "https://github.com/rafaelsantana6/zapo-rest/blob/main/src/app.ts"
click node_auth "https://github.com/rafaelsantana6/zapo-rest/blob/main/src/auth/plugin.ts"
click node_api_routes "https://github.com/rafaelsantana6/zapo-rest/tree/main/src/routes"
click node_instance_manager "https://github.com/rafaelsantana6/zapo-rest/blob/main/src/instances/manager.ts"
click node_instance_repo "https://github.com/rafaelsantana6/zapo-rest/blob/main/src/instances/repo.ts"
click node_wa_client "https://github.com/rafaelsantana6/zapo-rest/blob/main/src/instances/wa-client.ts"
click node_processor "https://github.com/rafaelsantana6/zapo-rest/blob/main/src/events/processor.ts"
click node_chat_store "https://github.com/rafaelsantana6/zapo-rest/blob/main/src/store/chats.ts"
click node_message_store "https://github.com/rafaelsantana6/zapo-rest/blob/main/src/store/messages.ts"
click node_contact_store "https://github.com/rafaelsantana6/zapo-rest/blob/main/src/store/contacts.ts"
click node_identity_map "https://github.com/rafaelsantana6/zapo-rest/blob/main/src/store/lid-map.ts"
click node_sse "https://github.com/rafaelsantana6/zapo-rest/blob/main/src/routes/events-sse.ts"
click node_webhooks "https://github.com/rafaelsantana6/zapo-rest/blob/main/src/webhooks/dispatcher.ts"
click node_webhook_outbox "https://github.com/rafaelsantana6/zapo-rest/blob/main/src/webhooks/outbox.ts"
click node_media_api "https://github.com/rafaelsantana6/zapo-rest/blob/main/src/routes/media.ts"
click node_media_storage "https://github.com/rafaelsantana6/zapo-rest/blob/main/src/media/storage.ts"
click node_voip "https://github.com/rafaelsantana6/zapo-rest/blob/main/src/routes/voip-ws.ts"
click node_call_recording "https://github.com/rafaelsantana6/zapo-rest/blob/main/src/voip/recording-manager.ts"
click node_call_store "https://github.com/rafaelsantana6/zapo-rest/blob/main/src/store/calls.ts"
click node_dashboard "https://github.com/rafaelsantana6/zapo-rest/blob/main/dashboard/src/App.tsx"
click node_dashboard_api "https://github.com/rafaelsantana6/zapo-rest/blob/main/dashboard/src/api/client.ts"
click node_softphone "https://github.com/rafaelsantana6/zapo-rest/blob/main/dashboard/src/components/Softphone.tsx"
click node_docs "https://github.com/rafaelsantana6/zapo-rest/tree/main/docs-site/src"

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_app,node_auth,node_api_routes,node_client toneBlue
class node_instance_manager,node_instance_repo,node_wa_client toneAmber
class node_processor,node_chat_store,node_message_store,node_contact_store,node_identity_map,node_postgres toneMint
class node_sse,node_webhooks,node_webhook_outbox,node_media_api,node_media_storage,node_object_store,node_voip,node_call_recording,node_call_store toneRose
class node_dashboard,node_dashboard_api,node_softphone,node_docs toneIndigo
```

## Components

### API and interfaces

- [Fastify application](https://github.com/rafaelsantana6/zapo-rest/blob/main/src/app.ts): `src/app.ts`
- [API-key authentication](https://github.com/rafaelsantana6/zapo-rest/blob/main/src/auth/plugin.ts): `src/auth/plugin.ts`
- [REST endpoints](https://github.com/rafaelsantana6/zapo-rest/tree/main/src/routes): `src/routes`

### Sessions and identity

- [Instance lifecycle](https://github.com/rafaelsantana6/zapo-rest/blob/main/src/instances/manager.ts): `src/instances/manager.ts`
- [Instance records](https://github.com/rafaelsantana6/zapo-rest/blob/main/src/instances/repo.ts): `src/instances/repo.ts`
- [WhatsApp client](https://github.com/rafaelsantana6/zapo-rest/blob/main/src/instances/wa-client.ts): `src/instances/wa-client.ts`

### Events and projections

- [Event processor](https://github.com/rafaelsantana6/zapo-rest/blob/main/src/events/processor.ts): `src/events/processor.ts`
- [Chat projections](https://github.com/rafaelsantana6/zapo-rest/blob/main/src/store/chats.ts): `src/store/chats.ts`
- [Message history](https://github.com/rafaelsantana6/zapo-rest/blob/main/src/store/messages.ts): `src/store/messages.ts`
- [Contact projections](https://github.com/rafaelsantana6/zapo-rest/blob/main/src/store/contacts.ts): `src/store/contacts.ts`
- [LID-to-PN mapping](https://github.com/rafaelsantana6/zapo-rest/blob/main/src/store/lid-map.ts): `src/store/lid-map.ts`
- **PostgreSQL**

### Media and integrations

- [Live event stream](https://github.com/rafaelsantana6/zapo-rest/blob/main/src/routes/events-sse.ts): `src/routes/events-sse.ts`
- [Webhook delivery](https://github.com/rafaelsantana6/zapo-rest/blob/main/src/webhooks/dispatcher.ts): `src/webhooks/dispatcher.ts`
- [Webhook outbox](https://github.com/rafaelsantana6/zapo-rest/blob/main/src/webhooks/outbox.ts): `src/webhooks/outbox.ts`
- [Media endpoints](https://github.com/rafaelsantana6/zapo-rest/blob/main/src/routes/media.ts): `src/routes/media.ts`
- [Media storage](https://github.com/rafaelsantana6/zapo-rest/blob/main/src/media/storage.ts): `src/media/storage.ts`
- **S3-compatible storage**
- [VoIP control and audio](https://github.com/rafaelsantana6/zapo-rest/blob/main/src/routes/voip-ws.ts): `src/routes/voip-ws.ts`
- [Call recording](https://github.com/rafaelsantana6/zapo-rest/blob/main/src/voip/recording-manager.ts): `src/voip/recording-manager.ts`
- [Call records](https://github.com/rafaelsantana6/zapo-rest/blob/main/src/store/calls.ts): `src/store/calls.ts`

### Operator experience

- [Operations dashboard](https://github.com/rafaelsantana6/zapo-rest/blob/main/dashboard/src/App.tsx): `dashboard/src/App.tsx`
- [Dashboard API client](https://github.com/rafaelsantana6/zapo-rest/blob/main/dashboard/src/api/client.ts): `dashboard/src/api/client.ts`
- [Dashboard softphone](https://github.com/rafaelsantana6/zapo-rest/blob/main/dashboard/src/components/Softphone.tsx): `dashboard/src/components/Softphone.tsx`
- [API guide and reference](https://github.com/rafaelsantana6/zapo-rest/tree/main/docs-site/src): `docs-site/src`

### Other components

- **API client**

## Connections

- API client → Fastify application: sends requests (evidence: `README.md`)
- Fastify application → API-key authentication: registers (evidence: `src/app.ts`)
- Fastify application → REST endpoints: registers (evidence: `src/app.ts`)
- REST endpoints → Instance lifecycle: uses sessions (evidence: `src/app.ts`)
- API-key authentication → Instance records: resolves keys (evidence: `src/auth/plugin.ts`)
- Instance lifecycle → Instance records: manages records (evidence: `src/instances/manager.ts`)
- Instance lifecycle → WhatsApp client: manages sessions (evidence: `src/instances/manager.ts`)
- WhatsApp client → Event processor: emits events
- Event processor → Chat projections: upserts chats (evidence: `src/events/processor.ts`)
- Event processor → Message history: projects messages (evidence: `src/events/processor.ts`)
- Event processor → Contact projections: updates contacts (evidence: `src/events/processor.ts`)
- Event processor → LID-to-PN mapping: records identity (evidence: `src/events/processor.ts`)
- Chat projections → PostgreSQL: reads and writes (evidence: `src/store/chats.ts`)
- Message history → PostgreSQL: persists history (evidence: `README.md`)
- Contact projections → PostgreSQL: persists contacts (evidence: `README.md`)
- LID-to-PN mapping → PostgreSQL: persists mappings (evidence: `README.md`)
- Event processor → Webhook delivery: dispatches events (evidence: `src/events/processor.ts`)
- Webhook delivery → Webhook outbox: queues delivery (evidence: `src/webhooks/dispatcher.ts`)
- Webhook outbox → API client: delivers retries (evidence: `README.md`)
- Event processor → Live event stream: publishes events (evidence: `README.md`)
- REST endpoints → Media endpoints: includes routes (evidence: `README.md`)
- Media endpoints → Media storage: serves media (evidence: `README.md`)
- Media storage → S3-compatible storage: stores objects (evidence: `README.md`)
- REST endpoints → VoIP control and audio: includes control (evidence: `README.md`)
- Call recording → Call records: updates recordings (evidence: `src/voip/recording-manager.ts`)
- Call recording → Media storage: stores recordings (evidence: `src/voip/recording-manager.ts`)
- Operations dashboard → Dashboard API client: calls API (evidence: `dashboard/src/App.tsx`)
- Operations dashboard → Dashboard softphone: renders (evidence: `dashboard/src/App.tsx`)
- Dashboard API client → Fastify application: calls REST API (evidence: `README.md`)
- API guide and reference → API client: documents API (evidence: `README.md`)
