# nauvalunesa/wa-gateway architecture

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

- Interactive diagram: https://gitdiagram.com/nauvalunesa/wa-gateway
- Repository: https://github.com/nauvalunesa/wa-gateway

## Overview

Utusan is a multi-session WhatsApp gateway with a React workspace and a Python REST API. The principal workflow is: sign in, pair a device, compose and send a message, then inspect delivery history. The product also supports broadcasts, channels, AI Rich messages, customer-service flows, auto-replies, and per-device profile and privacy controls. The graph groups these capabilities with the API, domain services, and WhatsApp runtime. Some feature routes are documented but unsampled; their links are included only where README or source-index evidence supports them.

Main entry points: [`gateway/application.py`](https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/application.py) (FastAPI application), [`gateway/whatsapp/clients.py`](https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/whatsapp/clients.py) (Session clients), [`gateway/routes/messages.py`](https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/routes/messages.py) (Message routes), [`frontend/src/App.tsx`](https://github.com/nauvalunesa/wa-gateway/blob/main/frontend/src/App.tsx) (Workspace pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace"]
  node_workspace_ui["Workspace pages<br/>[App.tsx]"]
  node_message_ui["Message composer<br/>[MessagePages.tsx]"]
  node_profile_ui["Profile controls"]
  node_cs_ui["Customer service editor"]
  node_web_api["API client<br/>[api.ts]"]
end

subgraph group_gateway["Gateway API"]
  node_app["FastAPI application<br/>[application.py]"]
  node_auth["Session and API-key auth<br/>[security.py]"]
  node_message_routes["Message routes<br/>[messages.py]"]
  node_device_routes["Device routes<br/>[devices.py]"]
  node_dashboard_routes["Dashboard routes<br/>[dashboard.py]"]
  node_cs_routes["Customer-service routes"]
  node_feature_routes["Feature routes"]
end

subgraph group_domain["Messaging services"]
  node_message_models["Message models<br/>[models.py]"]
  node_cs_models["Customer-service models<br/>[cs_models.py]"]
  node_cs_logic["Customer-service flows"]
  node_auto_reply["Auto-reply rules<br/>[auto_reply.py]"]
  node_blast["Broadcast service<br/>[blast.py]"]
  node_profile_service["Profile and privacy<br/>[profile_privacy.py]"]
end

subgraph group_runtime["WhatsApp and state"]
  node_clients["Session clients<br/>[clients.py]"]
  node_addressing["Recipient addressing<br/>[addressing.py]"]
  node_serialization["Message serialization<br/>[serialization.py]"]
  node_state["Runtime state<br/>[state.py]"]
  node_database[("Account and message store<br/>[database.py]")]
end

node_user(("Workspace user"))
node_whatsapp(("WhatsApp service"))

node_user -->|"uses"| node_workspace_ui
node_workspace_ui -->|"opens composer"| node_message_ui
node_workspace_ui -->|"opens profile"| node_profile_ui
node_workspace_ui -->|"opens bot editor"| node_cs_ui
node_message_ui -->|"sends requests"| node_web_api
node_profile_ui -->|"sends requests"| node_web_api
node_cs_ui -->|"sends requests"| node_web_api
node_web_api -->|"calls REST API"| node_app
node_app -->|"registers"| node_message_routes
node_app -->|"registers"| node_device_routes
node_app -->|"registers"| node_dashboard_routes
node_app -->|"registers"| node_cs_routes
node_app -->|"registers"| node_feature_routes
node_message_routes -->|"requires identity"| node_auth
node_cs_routes -->|"requires identity"| node_auth
node_cs_routes -->|"validates"| node_cs_models
node_cs_routes -->|"delegates to"| node_cs_logic
node_message_routes -->|"uses payloads"| node_message_models
node_message_routes -->|"resolves recipients"| node_addressing
node_message_routes -->|"sends via"| node_clients
node_feature_routes -.->|"supports broadcasts"| node_blast
node_feature_routes -.->|"supports rules"| node_auto_reply
node_feature_routes -.->|"supports profile controls"| node_profile_service
node_clients -->|"uses runtime state"| node_state
node_clients -->|"dispatches messages"| node_auto_reply
node_clients -->|"dispatches messages"| node_cs_logic
node_clients -->|"logs messages"| node_database
node_clients -->|"maintains sessions"| node_whatsapp
node_addressing -->|"converts identifiers"| node_serialization
node_cs_logic -->|"persists settings"| node_database
node_auto_reply -->|"reads rules"| node_database

click node_workspace_ui "https://github.com/nauvalunesa/wa-gateway/blob/main/frontend/src/App.tsx"
click node_message_ui "https://github.com/nauvalunesa/wa-gateway/blob/main/frontend/src/MessagePages.tsx"
click node_profile_ui "https://github.com/nauvalunesa/wa-gateway/blob/main/frontend/src/WhatsAppProfilePage.tsx"
click node_cs_ui "https://github.com/nauvalunesa/wa-gateway/blob/main/frontend/src/CustomerServicePage.tsx"
click node_web_api "https://github.com/nauvalunesa/wa-gateway/blob/main/frontend/src/api.ts"
click node_app "https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/application.py"
click node_auth "https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/security.py"
click node_message_routes "https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/routes/messages.py"
click node_device_routes "https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/routes/devices.py"
click node_dashboard_routes "https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/routes/dashboard.py"
click node_cs_routes "https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/routes/customer_service.py"
click node_feature_routes "https://github.com/nauvalunesa/wa-gateway/tree/main/gateway/routes"
click node_message_models "https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/messages/models.py"
click node_cs_models "https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/messages/cs_models.py"
click node_cs_logic "https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/services/customer_service.py"
click node_auto_reply "https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/services/auto_reply.py"
click node_blast "https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/services/blast.py"
click node_profile_service "https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/services/profile_privacy.py"
click node_clients "https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/whatsapp/clients.py"
click node_addressing "https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/whatsapp/addressing.py"
click node_serialization "https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/whatsapp/serialization.py"
click node_state "https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/state.py"
click node_database "https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/database.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_workspace_ui,node_message_ui,node_profile_ui,node_cs_ui,node_web_api,node_user toneBlue
class node_app,node_auth,node_message_routes,node_device_routes,node_dashboard_routes,node_cs_routes,node_feature_routes toneAmber
class node_message_models,node_cs_models,node_cs_logic,node_auto_reply,node_blast,node_profile_service toneMint
class node_clients,node_addressing,node_serialization,node_state,node_database toneRose
class node_whatsapp toneIndigo
```

## Components

### Workspace

- [Workspace pages](https://github.com/nauvalunesa/wa-gateway/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Message composer](https://github.com/nauvalunesa/wa-gateway/blob/main/frontend/src/MessagePages.tsx): `frontend/src/MessagePages.tsx`
- [Profile controls](https://github.com/nauvalunesa/wa-gateway/blob/main/frontend/src/WhatsAppProfilePage.tsx): `frontend/src/WhatsAppProfilePage.tsx`
- [Customer service editor](https://github.com/nauvalunesa/wa-gateway/blob/main/frontend/src/CustomerServicePage.tsx): `frontend/src/CustomerServicePage.tsx`
- [API client](https://github.com/nauvalunesa/wa-gateway/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### Gateway API

- [FastAPI application](https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/application.py): `gateway/application.py`
- [Session and API-key auth](https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/security.py): `gateway/security.py`
- [Message routes](https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/routes/messages.py): `gateway/routes/messages.py`
- [Device routes](https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/routes/devices.py): `gateway/routes/devices.py`
- [Dashboard routes](https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/routes/dashboard.py): `gateway/routes/dashboard.py`
- [Customer-service routes](https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/routes/customer_service.py): `gateway/routes/customer_service.py`
- [Feature routes](https://github.com/nauvalunesa/wa-gateway/tree/main/gateway/routes): `gateway/routes`

### Messaging services

- [Message models](https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/messages/models.py): `gateway/messages/models.py`
- [Customer-service models](https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/messages/cs_models.py): `gateway/messages/cs_models.py`
- [Customer-service flows](https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/services/customer_service.py): `gateway/services/customer_service.py`
- [Auto-reply rules](https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/services/auto_reply.py): `gateway/services/auto_reply.py`
- [Broadcast service](https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/services/blast.py): `gateway/services/blast.py`
- [Profile and privacy](https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/services/profile_privacy.py): `gateway/services/profile_privacy.py`

### WhatsApp and state

- [Session clients](https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/whatsapp/clients.py): `gateway/whatsapp/clients.py`
- [Recipient addressing](https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/whatsapp/addressing.py): `gateway/whatsapp/addressing.py`
- [Message serialization](https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/whatsapp/serialization.py): `gateway/whatsapp/serialization.py`
- [Runtime state](https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/state.py): `gateway/state.py`
- [Account and message store](https://github.com/nauvalunesa/wa-gateway/blob/main/gateway/database.py): `gateway/database.py`

### Other components

- **Workspace user**
- **WhatsApp service**

## Connections

- Workspace user → Workspace pages: uses
- Workspace pages → Message composer: opens composer (evidence: `frontend/src/App.tsx`)
- Workspace pages → Profile controls: opens profile (evidence: `frontend/src/App.tsx`)
- Workspace pages → Customer service editor: opens bot editor (evidence: `frontend/src/App.tsx`)
- Message composer → API client: sends requests (evidence: `frontend/src/MessagePages.tsx`)
- Profile controls → API client: sends requests (evidence: `frontend/src/WhatsAppProfilePage.tsx`)
- Customer service editor → API client: sends requests (evidence: `frontend/src/CustomerServicePage.tsx`)
- API client → FastAPI application: calls REST API
- FastAPI application → Message routes: registers (evidence: `gateway/application.py`)
- FastAPI application → Device routes: registers (evidence: `gateway/application.py`)
- FastAPI application → Dashboard routes: registers (evidence: `gateway/application.py`)
- FastAPI application → Customer-service routes: registers (evidence: `gateway/application.py`)
- FastAPI application → Feature routes: registers (evidence: `gateway/application.py`)
- Message routes → Session and API-key auth: requires identity (evidence: `gateway/routes/messages.py`)
- Customer-service routes → Session and API-key auth: requires identity (evidence: `gateway/routes/customer_service.py`)
- Customer-service routes → Customer-service models: validates (evidence: `gateway/routes/customer_service.py`)
- Customer-service routes → Customer-service flows: delegates to (evidence: `gateway/routes/customer_service.py`)
- Message routes → Message models: uses payloads (evidence: `gateway/routes/messages.py`)
- Message routes → Recipient addressing: resolves recipients (evidence: `gateway/routes/messages.py`)
- Message routes → Session clients: sends via (evidence: `gateway/routes/messages.py`)
- Feature routes → Broadcast service: supports broadcasts
- Feature routes → Auto-reply rules: supports rules (evidence: `gateway/routes/dashboard.py`)
- Feature routes → Profile and privacy: supports profile controls
- Session clients → Runtime state: uses runtime state (evidence: `gateway/whatsapp/clients.py`)
- Session clients → Auto-reply rules: dispatches messages (evidence: `gateway/whatsapp/clients.py`)
- Session clients → Customer-service flows: dispatches messages (evidence: `gateway/whatsapp/clients.py`)
- Session clients → Account and message store: logs messages (evidence: `gateway/whatsapp/clients.py`)
- Session clients → WhatsApp service: maintains sessions
- Recipient addressing → Message serialization: converts identifiers (evidence: `gateway/whatsapp/addressing.py`)
- Customer-service flows → Account and message store: persists settings (evidence: `gateway/services/customer_service.py`)
- Auto-reply rules → Account and message store: reads rules (evidence: `gateway/services/auto_reply.py`)
