# bocahlinux/wamora architecture

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

- Interactive diagram: https://gitdiagram.com/bocahlinux/wamora
- Repository: https://github.com/bocahlinux/wamora

## Overview

Wamora is an internal dashboard for monitoring and operating a WAHA-based WhatsApp gateway. Operators sign in to view dashboard, inbox, and session state, manage WhatsApp sessions, and create or review controlled bulk-send campaigns. WAHA webhooks feed durable message records; reconciliation repairs missed history, while approved blast campaigns dispatch recipient-level sends through the BFF. The React UI uses the BFF for WAHA-facing operations; the BFF also makes best-effort internal calls to Django. README documents reports and settings capabilities, but their implementation wiring was not sampled.

Main entry points: [`bff/src/wahaClient.ts`](https://github.com/bocahlinux/wamora/blob/main/bff/src/wahaClient.ts) (WAHA client), [`bff/src/app.ts`](https://github.com/bocahlinux/wamora/blob/main/bff/src/app.ts) (BFF router), [`backend/apps/webhooks/services.py`](https://github.com/bocahlinux/wamora/blob/main/backend/apps/webhooks/services.py) (Webhook processing), [`backend/apps/blast/tasks.py`](https://github.com/bocahlinux/wamora/blob/main/backend/apps/blast/tasks.py) (Blast dispatch tasks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Operator interface"]
  node_frontend["Dashboard UI<br/>[App.tsx]"]
  node_routes["Protected pages<br/>[AppRoutes.tsx]"]
  node_query["Query state<br/>[useApiQuery.ts]"]
  node_sessions["Session controls<br/>[SessionsPage.tsx]"]
end

subgraph group_gateway["BFF gateway"]
  node_bffapp["BFF router<br/>[app.ts]"]
  node_bffsession["Session API<br/>[session.ts]"]
  node_bffmessages["Message API<br/>[messages.ts]"]
  node_bffblast["Blast API<br/>[internalBlast.ts]"]
  node_wahaclient["WAHA client<br/>[wahaClient.ts]"]
  node_django_client["Django client<br/>[djangoClient.ts]"]
end

subgraph group_ingest["Ingestion and sync"]
  node_webhook["Webhook intake<br/>[views.py]"]
  node_webhook_service["Webhook processing<br/>[services.py]"]
  node_sync_tasks["Sync tasks<br/>[tasks.py]"]
  node_reconcile["Reconciliation<br/>[reconciliation.py]"]
  node_sync_client["Reconciliation WAHA client<br/>[waha_client.py]"]
end

subgraph group_campaigns["Campaign dispatch"]
  node_blast_tasks["Blast dispatch tasks<br/>[tasks.py]"]
  node_blast_client["BFF dispatch client<br/>[bff_client.py]"]
  node_blast_api["Campaign API<br/>[views.py]"]
end

subgraph group_backend["Backend services and state"]
  node_operations[("Outbound operations<br/>[models.py]")]
  node_chats[("Chat and messages<br/>[models.py]")]
  node_sessions_db[("WAHA sessions<br/>[models.py]")]
  node_audit["Audit service<br/>[views.py]"]
end

node_operator(("Operator"))
node_waha["WAHA gateway"]
node_postgres[("PostgreSQL")]
node_queue["Celery and Redis"]

node_operator -->|"uses"| node_frontend
node_frontend -->|"renders"| node_routes
node_routes -->|"routes to"| node_sessions
node_sessions -->|"loads status"| node_query
node_frontend -->|"calls APIs"| node_bffapp
node_bffapp -->|"dispatches"| node_bffsession
node_bffapp -->|"dispatches"| node_bffmessages
node_bffapp -->|"dispatches"| node_bffblast
node_bffsession -->|"requests WAHA"| node_wahaclient
node_bffmessages -->|"requests WAHA"| node_wahaclient
node_bffblast -->|"sends via"| node_wahaclient
node_wahaclient -->|"calls allowlisted API"| node_waha
node_wahaclient -.->|"reports outcomes"| node_django_client
node_waha -->|"posts events"| node_webhook
node_webhook -->|"processes event"| node_webhook_service
node_webhook_service -->|"persists messages"| node_chats
node_webhook_service -->|"resolves session"| node_sessions_db
node_webhook_service -->|"writes records"| node_postgres
node_sync_tasks -->|"runs reconciliation"| node_reconcile
node_reconcile -->|"fetches history"| node_sync_client
node_sync_client -->|"reads chats"| node_waha
node_reconcile -->|"repairs history"| node_chats
node_sync_tasks -->|"schedules work"| node_queue
node_blast_api -->|"schedules campaign"| node_blast_tasks
node_blast_tasks -->|"dispatches recipient"| node_blast_client
node_blast_client -->|"sends internally"| node_bffblast
node_blast_tasks -->|"claims and records"| node_operations
node_blast_tasks -->|"schedules recipients"| node_queue
node_operations -->|"stores state"| node_postgres
node_chats -->|"stores messages"| node_postgres
node_sessions_db -->|"stores sessions"| node_postgres
node_django_client -.->|"writes audit events"| node_audit
node_blast_api -->|"persists campaigns"| node_postgres

click node_frontend "https://github.com/bocahlinux/wamora/blob/main/frontend/src/App.tsx"
click node_routes "https://github.com/bocahlinux/wamora/blob/main/frontend/src/routes/AppRoutes.tsx"
click node_query "https://github.com/bocahlinux/wamora/blob/main/frontend/src/lib/useApiQuery.ts"
click node_sessions "https://github.com/bocahlinux/wamora/blob/main/frontend/src/pages/SessionsPage.tsx"
click node_bffapp "https://github.com/bocahlinux/wamora/blob/main/bff/src/app.ts"
click node_bffsession "https://github.com/bocahlinux/wamora/blob/main/bff/src/routes/session.ts"
click node_bffmessages "https://github.com/bocahlinux/wamora/blob/main/bff/src/routes/messages.ts"
click node_bffblast "https://github.com/bocahlinux/wamora/blob/main/bff/src/routes/internalBlast.ts"
click node_wahaclient "https://github.com/bocahlinux/wamora/blob/main/bff/src/wahaClient.ts"
click node_django_client "https://github.com/bocahlinux/wamora/blob/main/bff/src/djangoClient.ts"
click node_webhook "https://github.com/bocahlinux/wamora/blob/main/backend/apps/webhooks/views.py"
click node_webhook_service "https://github.com/bocahlinux/wamora/blob/main/backend/apps/webhooks/services.py"
click node_sync_tasks "https://github.com/bocahlinux/wamora/blob/main/backend/apps/sync/tasks.py"
click node_reconcile "https://github.com/bocahlinux/wamora/blob/main/backend/apps/sync/reconciliation.py"
click node_sync_client "https://github.com/bocahlinux/wamora/blob/main/backend/apps/sync/waha_client.py"
click node_blast_tasks "https://github.com/bocahlinux/wamora/blob/main/backend/apps/blast/tasks.py"
click node_blast_client "https://github.com/bocahlinux/wamora/blob/main/backend/apps/blast/bff_client.py"
click node_blast_api "https://github.com/bocahlinux/wamora/blob/main/backend/apps/blast/views.py"
click node_operations "https://github.com/bocahlinux/wamora/blob/main/backend/apps/operations/models.py"
click node_chats "https://github.com/bocahlinux/wamora/blob/main/backend/apps/chats/models.py"
click node_sessions_db "https://github.com/bocahlinux/wamora/blob/main/backend/apps/waha_sessions/models.py"
click node_audit "https://github.com/bocahlinux/wamora/blob/main/backend/apps/audit/views.py"

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_frontend,node_routes,node_query,node_sessions toneBlue
class node_bffapp,node_bffsession,node_bffmessages,node_bffblast,node_wahaclient,node_django_client,node_postgres,node_queue toneAmber
class node_webhook,node_webhook_service,node_sync_tasks,node_reconcile,node_sync_client toneMint
class node_blast_tasks,node_blast_client,node_blast_api toneRose
class node_operations,node_chats,node_sessions_db,node_audit,node_operator,node_waha toneIndigo
```

## Components

### Operator interface

- [Dashboard UI](https://github.com/bocahlinux/wamora/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Protected pages](https://github.com/bocahlinux/wamora/blob/main/frontend/src/routes/AppRoutes.tsx): `frontend/src/routes/AppRoutes.tsx`
- [Query state](https://github.com/bocahlinux/wamora/blob/main/frontend/src/lib/useApiQuery.ts): `frontend/src/lib/useApiQuery.ts`
- [Session controls](https://github.com/bocahlinux/wamora/blob/main/frontend/src/pages/SessionsPage.tsx): `frontend/src/pages/SessionsPage.tsx`

### BFF gateway

- [BFF router](https://github.com/bocahlinux/wamora/blob/main/bff/src/app.ts): `bff/src/app.ts`
- [Session API](https://github.com/bocahlinux/wamora/blob/main/bff/src/routes/session.ts): `bff/src/routes/session.ts`
- [Message API](https://github.com/bocahlinux/wamora/blob/main/bff/src/routes/messages.ts): `bff/src/routes/messages.ts`
- [Blast API](https://github.com/bocahlinux/wamora/blob/main/bff/src/routes/internalBlast.ts): `bff/src/routes/internalBlast.ts`
- [WAHA client](https://github.com/bocahlinux/wamora/blob/main/bff/src/wahaClient.ts): `bff/src/wahaClient.ts`
- [Django client](https://github.com/bocahlinux/wamora/blob/main/bff/src/djangoClient.ts): `bff/src/djangoClient.ts`

### Ingestion and sync

- [Webhook intake](https://github.com/bocahlinux/wamora/blob/main/backend/apps/webhooks/views.py): `backend/apps/webhooks/views.py`
- [Webhook processing](https://github.com/bocahlinux/wamora/blob/main/backend/apps/webhooks/services.py): `backend/apps/webhooks/services.py`
- [Sync tasks](https://github.com/bocahlinux/wamora/blob/main/backend/apps/sync/tasks.py): `backend/apps/sync/tasks.py`
- [Reconciliation](https://github.com/bocahlinux/wamora/blob/main/backend/apps/sync/reconciliation.py): `backend/apps/sync/reconciliation.py`
- [Reconciliation WAHA client](https://github.com/bocahlinux/wamora/blob/main/backend/apps/sync/waha_client.py): `backend/apps/sync/waha_client.py`

### Campaign dispatch

- [Blast dispatch tasks](https://github.com/bocahlinux/wamora/blob/main/backend/apps/blast/tasks.py): `backend/apps/blast/tasks.py`
- [BFF dispatch client](https://github.com/bocahlinux/wamora/blob/main/backend/apps/blast/bff_client.py): `backend/apps/blast/bff_client.py`
- [Campaign API](https://github.com/bocahlinux/wamora/blob/main/backend/apps/blast/views.py): `backend/apps/blast/views.py`

### Backend services and state

- [Outbound operations](https://github.com/bocahlinux/wamora/blob/main/backend/apps/operations/models.py): `backend/apps/operations/models.py`
- [Chat and messages](https://github.com/bocahlinux/wamora/blob/main/backend/apps/chats/models.py): `backend/apps/chats/models.py`
- [WAHA sessions](https://github.com/bocahlinux/wamora/blob/main/backend/apps/waha_sessions/models.py): `backend/apps/waha_sessions/models.py`
- [Audit service](https://github.com/bocahlinux/wamora/blob/main/backend/apps/audit/views.py): `backend/apps/audit/views.py`

### Other components

- **Operator**
- **WAHA gateway**
- **PostgreSQL**
- **Celery and Redis**

## Connections

- Operator → Dashboard UI: uses
- Dashboard UI → Protected pages: renders
- Protected pages → Session controls: routes to
- Session controls → Query state: loads status
- Dashboard UI → BFF router: calls APIs
- BFF router → Session API: dispatches
- BFF router → Message API: dispatches
- BFF router → Blast API: dispatches
- Session API → WAHA client: requests WAHA
- Message API → WAHA client: requests WAHA
- Blast API → WAHA client: sends via
- WAHA client → WAHA gateway: calls allowlisted API
- WAHA client → Django client: reports outcomes
- WAHA gateway → Webhook intake: posts events
- Webhook intake → Webhook processing: processes event
- Webhook processing → Chat and messages: persists messages
- Webhook processing → WAHA sessions: resolves session
- Webhook processing → PostgreSQL: writes records
- Sync tasks → Reconciliation: runs reconciliation
- Reconciliation → Reconciliation WAHA client: fetches history
- Reconciliation WAHA client → WAHA gateway: reads chats
- Reconciliation → Chat and messages: repairs history
- Sync tasks → Celery and Redis: schedules work
- Campaign API → Blast dispatch tasks: schedules campaign
- Blast dispatch tasks → BFF dispatch client: dispatches recipient
- BFF dispatch client → Blast API: sends internally
- Blast dispatch tasks → Outbound operations: claims and records
- Blast dispatch tasks → Celery and Redis: schedules recipients
- Outbound operations → PostgreSQL: stores state
- Chat and messages → PostgreSQL: stores messages
- WAHA sessions → PostgreSQL: stores sessions
- Django client → Audit service: writes audit events
- Campaign API → PostgreSQL: persists campaigns