# asternic/wuzapi architecture

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

- Interactive diagram: https://gitdiagram.com/asternic/wuzapi
- Repository: https://github.com/asternic/wuzapi

## Overview

WuzAPI is a multi-device WhatsApp REST API. A client or operator sends authenticated HTTP requests; the server routes them to session, messaging, user, chat, and group handlers, which operate WhatsApp sessions and return API responses. Incoming WhatsApp events can be delivered through configured webhooks or RabbitMQ. Database-backed account/configuration state, message history, and media handling support those capabilities; optional S3 provides media storage. The README documents the broader endpoint set, while some subsystem connections are not visible in the sampled excerpts, so those links are omitted.

Main entry points: [`handlers.go`](https://github.com/asternic/wuzapi/blob/main/handlers.go) (Session and messaging), [`routes.go`](https://github.com/asternic/wuzapi/blob/main/routes.go) (HTTP routes), [`db.go`](https://github.com/asternic/wuzapi/blob/main/db.go) (Application database), [`main.go`](https://github.com/asternic/wuzapi/blob/main/main.go) (Server startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Service entry"]
  node_server["Server startup<br/>[main.go]"]
  node_routing["HTTP routes<br/>[routes.go]"]
  node_dashboard["Dashboard UI<br/>[app.js]"]
  node_stdio["Stdio interface<br/>[stdio.go]"]
end

subgraph group_api["REST capabilities"]
  node_session["Session and messaging<br/>[handlers.go]"]
  node_groups["Group operations<br/>[handlers.go]"]
  node_group_requests["Join requests"]
end

subgraph group_state["State and media"]
  node_clients["Session client manager<br/>[clients.go]"]
  node_database[("Application database<br/>[db.go]")]
  node_migrations["Schema migrations<br/>[migrations.go]"]
  node_history["Message history<br/>[history_sync.go]"]
  node_media["Media processing<br/>[media_sources.go]"]
  node_media_delivery["Media delivery<br/>[media_delivery.go]"]
  node_media_store["Temporary media store<br/>[media_store.go]"]
  node_s3["S3 storage<br/>[s3manager.go]"]
end

subgraph group_events["Events and integrations"]
  node_webhooks["Webhook events<br/>[wmiau.go]"]
  node_rabbitmq["RabbitMQ events<br/>[rabbitmq.go]"]
end

node_operator(("API client"))
node_whatsapp["WhatsApp service"]

node_operator -->|"sends requests"| node_routing
node_server -->|"registers routes"| node_routing
node_routing -->|"routes requests"| node_session
node_routing -->|"routes requests"| node_groups
node_routing -.->|"routes requests"| node_group_requests
node_dashboard -->|"calls API"| node_routing
node_session -->|"controls sessions"| node_whatsapp
node_groups -->|"manages groups"| node_whatsapp
node_group_requests -->|"requests participants"| node_whatsapp
node_session -->|"gets session client"| node_clients
node_session -->|"reads configuration"| node_database
node_database -.->|"schema setup"| node_migrations
node_history -.->|"stores history"| node_database
node_session -.->|"records messages"| node_history
node_media -.->|"uses temporary files"| node_media_store
node_media_delivery -.->|"prepares delivery files"| node_media_store
node_s3 -->|"reads user config"| node_database
node_session -.->|"handles attachments"| node_media
node_webhooks -->|"delivers events"| node_operator
node_session -->|"publishes events"| node_rabbitmq
node_server -->|"starts stdio mode"| node_stdio

click node_server "https://github.com/asternic/wuzapi/blob/main/main.go"
click node_routing "https://github.com/asternic/wuzapi/blob/main/routes.go"
click node_dashboard "https://github.com/asternic/wuzapi/blob/main/static/dashboard/js/app.js"
click node_session "https://github.com/asternic/wuzapi/blob/main/handlers.go"
click node_groups "https://github.com/asternic/wuzapi/blob/main/handlers.go"
click node_group_requests "https://github.com/asternic/wuzapi/blob/main/handlers_grouprequests.go"
click node_clients "https://github.com/asternic/wuzapi/blob/main/clients.go"
click node_database "https://github.com/asternic/wuzapi/blob/main/db.go"
click node_migrations "https://github.com/asternic/wuzapi/blob/main/migrations.go"
click node_history "https://github.com/asternic/wuzapi/blob/main/history_sync.go"
click node_media "https://github.com/asternic/wuzapi/blob/main/media_sources.go"
click node_media_delivery "https://github.com/asternic/wuzapi/blob/main/media_delivery.go"
click node_media_store "https://github.com/asternic/wuzapi/blob/main/media_store.go"
click node_s3 "https://github.com/asternic/wuzapi/blob/main/s3manager.go"
click node_webhooks "https://github.com/asternic/wuzapi/blob/main/wmiau.go"
click node_rabbitmq "https://github.com/asternic/wuzapi/blob/main/rabbitmq.go"
click node_stdio "https://github.com/asternic/wuzapi/blob/main/stdio.go"

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_server,node_routing,node_dashboard,node_stdio,node_operator toneBlue
class node_session,node_groups,node_group_requests toneAmber
class node_clients,node_database,node_migrations,node_history,node_media,node_media_delivery,node_media_store,node_s3 toneMint
class node_webhooks,node_rabbitmq toneRose
class node_whatsapp toneIndigo
```

## Components

### Service entry

- [Server startup](https://github.com/asternic/wuzapi/blob/main/main.go): `main.go`
- [HTTP routes](https://github.com/asternic/wuzapi/blob/main/routes.go): `routes.go`
- [Dashboard UI](https://github.com/asternic/wuzapi/blob/main/static/dashboard/js/app.js): `static/dashboard/js/app.js`
- [Stdio interface](https://github.com/asternic/wuzapi/blob/main/stdio.go): `stdio.go`

### REST capabilities

- [Session and messaging](https://github.com/asternic/wuzapi/blob/main/handlers.go): `handlers.go`
- [Group operations](https://github.com/asternic/wuzapi/blob/main/handlers.go): `handlers.go`
- [Join requests](https://github.com/asternic/wuzapi/blob/main/handlers_grouprequests.go): `handlers_grouprequests.go`

### State and media

- [Session client manager](https://github.com/asternic/wuzapi/blob/main/clients.go): `clients.go`
- [Application database](https://github.com/asternic/wuzapi/blob/main/db.go): `db.go`
- [Schema migrations](https://github.com/asternic/wuzapi/blob/main/migrations.go): `migrations.go`
- [Message history](https://github.com/asternic/wuzapi/blob/main/history_sync.go): `history_sync.go`
- [Media processing](https://github.com/asternic/wuzapi/blob/main/media_sources.go): `media_sources.go`
- [Media delivery](https://github.com/asternic/wuzapi/blob/main/media_delivery.go): `media_delivery.go`
- [Temporary media store](https://github.com/asternic/wuzapi/blob/main/media_store.go): `media_store.go`
- [S3 storage](https://github.com/asternic/wuzapi/blob/main/s3manager.go): `s3manager.go`

### Events and integrations

- [Webhook events](https://github.com/asternic/wuzapi/blob/main/wmiau.go): `wmiau.go`
- [RabbitMQ events](https://github.com/asternic/wuzapi/blob/main/rabbitmq.go): `rabbitmq.go`

### Other components

- **API client**
- **WhatsApp service**

## Connections

- API client → HTTP routes: sends requests (evidence: `README.md`)
- Server startup → HTTP routes: registers routes (evidence: `main.go`)
- HTTP routes → Session and messaging: routes requests (evidence: `routes.go`)
- HTTP routes → Group operations: routes requests (evidence: `routes.go`)
- HTTP routes → Join requests: routes requests
- Dashboard UI → HTTP routes: calls API (evidence: `static/dashboard/js/app.js`)
- Session and messaging → WhatsApp service: controls sessions (evidence: `README.md`)
- Group operations → WhatsApp service: manages groups (evidence: `README.md`)
- Join requests → WhatsApp service: requests participants (evidence: `handlers_grouprequests.go`)
- Session and messaging → Session client manager: gets session client (evidence: `handlers.go`)
- Session and messaging → Application database: reads configuration (evidence: `handlers.go`)
- Application database → Schema migrations: schema setup
- Message history → Application database: stores history
- Session and messaging → Message history: records messages
- Media processing → Temporary media store: uses temporary files
- Media delivery → Temporary media store: prepares delivery files
- S3 storage → Application database: reads user config (evidence: `s3manager.go`)
- Session and messaging → Media processing: handles attachments
- Webhook events → API client: delivers events (evidence: `README.md`)
- Session and messaging → RabbitMQ events: publishes events (evidence: `handlers.go`)
- Server startup → Stdio interface: starts stdio mode (evidence: `main.go`)
