# clairton/unoapi-cloud architecture

> Architecture diagram of the GitHub repository clairton/unoapi-cloud, 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/clairton/unoapi-cloud
- Repository: https://github.com/clairton/unoapi-cloud

## Overview

Unoapi Cloud exposes a WhatsApp Cloud API-compatible REST service backed primarily by Baileys. A client submits API requests; controllers delegate message operations through the incoming/client layer to a WhatsApp session, while received events are normalized and delivered through the outgoing webhook layer. Session setup, media, templates, contacts, registration, and bulk/message-related jobs are additional product capabilities. The entry point’s concrete wiring and sampled controllers establish the main connections; unsampled routes and job dispatch details are represented only where their paths and roles are evident.

Main entry points: [`src/router.ts`](https://github.com/clairton/unoapi-cloud/blob/main/src/router.ts) (Route Dispatch), [`src/services/client_baileys.ts`](https://github.com/clairton/unoapi-cloud/blob/main/src/services/client_baileys.ts) (Baileys Client), [`src/controllers/session_controller.ts`](https://github.com/clairton/unoapi-cloud/blob/main/src/controllers/session_controller.ts) (Session API), [`src/services/listener_baileys.ts`](https://github.com/clairton/unoapi-cloud/blob/main/src/services/listener_baileys.ts) (Event Listener)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["REST API"]
  node_app["HTTP App<br/>[app.ts]"]
  node_router["Route Dispatch<br/>[router.ts]"]
  node_messages["Message API"]
  node_media["Media API"]
  node_templates["Template API"]
  node_contacts["Contact API"]
  node_registration["Registration API"]
  node_sessions["Session API"]
end

subgraph group_messaging["Messaging Runtime"]
  node_incoming["Incoming Service"]
  node_client["Baileys Client<br/>[client_baileys.ts]"]
  node_forward["Forward Client<br/>[client_forward.ts]"]
  node_listener["Event Listener"]
  node_jobs["Message Jobs<br/>[incoming.ts]"]
  node_socket["WhatsApp Adapter<br/>[socket.ts]"]
end

subgraph group_session["Session and State"]
  node_config["Configuration<br/>[config_by_env.ts]"]
  node_sessionstore[("Session Store")]
  node_datastore[("Data Store<br/>[data_store.ts]")]
  node_media_store[("Media Store<br/>[media_store.ts]")]
end

subgraph group_integrations["Delivery and Integrations"]
  node_outgoing["Cloud API Output"]
  node_webhook["Webhook Receiver"]
  node_broadcast["Socket Broadcast<br/>[broadcast.ts]"]
  node_bulk["Bulk Processing<br/>[bulker.ts]"]
end

node_user(("API Client"))
node_wa(("WhatsApp"))
node_webhook_target(("Webhook Target"))

node_user -->|"HTTP requests"| node_app
node_app -->|"mounts routes"| node_router
node_router -->|"dispatches"| node_messages
node_router -->|"dispatches"| node_media
node_router -->|"dispatches"| node_templates
node_router -->|"dispatches"| node_contacts
node_router -->|"dispatches"| node_registration
node_router -->|"dispatches"| node_sessions
node_messages -->|"sends request"| node_incoming
node_incoming -->|"selects client"| node_client
node_incoming -.->|"selects client"| node_forward
node_client -->|"calls adapter"| node_socket
node_socket -->|"session messaging"| node_wa
node_wa -->|"session events"| node_socket
node_client -->|"emits events"| node_listener
node_listener -->|"sends webhooks"| node_outgoing
node_outgoing -->|"POST events"| node_webhook_target
node_webhook -.->|"forwards payload"| node_incoming
node_sessions -->|"loads config"| node_config
node_sessions -->|"reads status"| node_sessionstore
node_sessions -->|"starts connection"| node_socket
node_client -->|"loads config"| node_config
node_client -->|"tracks status"| node_sessionstore
node_listener -->|"stores message state"| node_datastore
node_media -->|"retrieves media"| node_media_store
node_templates -->|"loads templates"| node_datastore
node_contacts -.->|"contact operation"| node_client
node_registration -.->|"updates session"| node_sessionstore
node_listener -->|"broadcasts events"| node_broadcast
node_bulk -.->|"delivers payload"| node_outgoing
node_messages -->|"reports errors"| node_outgoing

click node_app "https://github.com/clairton/unoapi-cloud/blob/main/src/app.ts"
click node_router "https://github.com/clairton/unoapi-cloud/blob/main/src/router.ts"
click node_messages "https://github.com/clairton/unoapi-cloud/blob/main/src/controllers/messages_controller.ts"
click node_media "https://github.com/clairton/unoapi-cloud/blob/main/src/controllers/media_controller.ts"
click node_templates "https://github.com/clairton/unoapi-cloud/blob/main/src/controllers/templates_controller.ts"
click node_contacts "https://github.com/clairton/unoapi-cloud/blob/main/src/controllers/contacts_controller.ts"
click node_registration "https://github.com/clairton/unoapi-cloud/blob/main/src/controllers/registration_controller.ts"
click node_sessions "https://github.com/clairton/unoapi-cloud/blob/main/src/controllers/session_controller.ts"
click node_incoming "https://github.com/clairton/unoapi-cloud/blob/main/src/services/incoming_baileys.ts"
click node_client "https://github.com/clairton/unoapi-cloud/blob/main/src/services/client_baileys.ts"
click node_forward "https://github.com/clairton/unoapi-cloud/blob/main/src/services/client_forward.ts"
click node_listener "https://github.com/clairton/unoapi-cloud/blob/main/src/services/listener_baileys.ts"
click node_jobs "https://github.com/clairton/unoapi-cloud/blob/main/src/jobs/incoming.ts"
click node_socket "https://github.com/clairton/unoapi-cloud/blob/main/src/services/socket.ts"
click node_config "https://github.com/clairton/unoapi-cloud/blob/main/src/services/config_by_env.ts"
click node_sessionstore "https://github.com/clairton/unoapi-cloud/blob/main/src/services/session_store_file.ts"
click node_datastore "https://github.com/clairton/unoapi-cloud/blob/main/src/services/data_store.ts"
click node_media_store "https://github.com/clairton/unoapi-cloud/blob/main/src/services/media_store.ts"
click node_outgoing "https://github.com/clairton/unoapi-cloud/blob/main/src/services/outgoing_cloud_api.ts"
click node_webhook "https://github.com/clairton/unoapi-cloud/blob/main/src/controllers/webhook_controller.ts"
click node_broadcast "https://github.com/clairton/unoapi-cloud/blob/main/src/services/broadcast.ts"
click node_bulk "https://github.com/clairton/unoapi-cloud/blob/main/src/bulker.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_app,node_router,node_messages,node_media,node_templates,node_contacts,node_registration,node_sessions,node_user toneBlue
class node_incoming,node_client,node_forward,node_listener,node_jobs,node_socket toneAmber
class node_config,node_sessionstore,node_datastore,node_media_store,node_webhook_target toneMint
class node_outgoing,node_webhook,node_broadcast,node_bulk toneRose
class node_wa toneIndigo
```

## Components

### REST API

- [HTTP App](https://github.com/clairton/unoapi-cloud/blob/main/src/app.ts): `src/app.ts`
- [Route Dispatch](https://github.com/clairton/unoapi-cloud/blob/main/src/router.ts): `src/router.ts`
- [Message API](https://github.com/clairton/unoapi-cloud/blob/main/src/controllers/messages_controller.ts): `src/controllers/messages_controller.ts`
- [Media API](https://github.com/clairton/unoapi-cloud/blob/main/src/controllers/media_controller.ts): `src/controllers/media_controller.ts`
- [Template API](https://github.com/clairton/unoapi-cloud/blob/main/src/controllers/templates_controller.ts): `src/controllers/templates_controller.ts`
- [Contact API](https://github.com/clairton/unoapi-cloud/blob/main/src/controllers/contacts_controller.ts): `src/controllers/contacts_controller.ts`
- [Registration API](https://github.com/clairton/unoapi-cloud/blob/main/src/controllers/registration_controller.ts): `src/controllers/registration_controller.ts`
- [Session API](https://github.com/clairton/unoapi-cloud/blob/main/src/controllers/session_controller.ts): `src/controllers/session_controller.ts`

### Messaging Runtime

- [Incoming Service](https://github.com/clairton/unoapi-cloud/blob/main/src/services/incoming_baileys.ts): `src/services/incoming_baileys.ts`
- [Baileys Client](https://github.com/clairton/unoapi-cloud/blob/main/src/services/client_baileys.ts): `src/services/client_baileys.ts`
- [Forward Client](https://github.com/clairton/unoapi-cloud/blob/main/src/services/client_forward.ts): `src/services/client_forward.ts`
- [Event Listener](https://github.com/clairton/unoapi-cloud/blob/main/src/services/listener_baileys.ts): `src/services/listener_baileys.ts`
- [Message Jobs](https://github.com/clairton/unoapi-cloud/blob/main/src/jobs/incoming.ts): `src/jobs/incoming.ts`
- [WhatsApp Adapter](https://github.com/clairton/unoapi-cloud/blob/main/src/services/socket.ts): `src/services/socket.ts`

### Session and State

- [Configuration](https://github.com/clairton/unoapi-cloud/blob/main/src/services/config_by_env.ts): `src/services/config_by_env.ts`
- [Session Store](https://github.com/clairton/unoapi-cloud/blob/main/src/services/session_store_file.ts): `src/services/session_store_file.ts`
- [Data Store](https://github.com/clairton/unoapi-cloud/blob/main/src/services/data_store.ts): `src/services/data_store.ts`
- [Media Store](https://github.com/clairton/unoapi-cloud/blob/main/src/services/media_store.ts): `src/services/media_store.ts`

### Delivery and Integrations

- [Cloud API Output](https://github.com/clairton/unoapi-cloud/blob/main/src/services/outgoing_cloud_api.ts): `src/services/outgoing_cloud_api.ts`
- [Webhook Receiver](https://github.com/clairton/unoapi-cloud/blob/main/src/controllers/webhook_controller.ts): `src/controllers/webhook_controller.ts`
- [Socket Broadcast](https://github.com/clairton/unoapi-cloud/blob/main/src/services/broadcast.ts): `src/services/broadcast.ts`
- [Bulk Processing](https://github.com/clairton/unoapi-cloud/blob/main/src/bulker.ts): `src/bulker.ts`

### Other components

- **API Client**
- **WhatsApp**
- **Webhook Target**

## Connections

- API Client → HTTP App: HTTP requests
- HTTP App → Route Dispatch: mounts routes
- Route Dispatch → Message API: dispatches
- Route Dispatch → Media API: dispatches
- Route Dispatch → Template API: dispatches
- Route Dispatch → Contact API: dispatches
- Route Dispatch → Registration API: dispatches
- Route Dispatch → Session API: dispatches
- Message API → Incoming Service: sends request
- Incoming Service → Baileys Client: selects client
- Incoming Service → Forward Client: selects client
- Baileys Client → WhatsApp Adapter: calls adapter
- WhatsApp Adapter → WhatsApp: session messaging
- WhatsApp → WhatsApp Adapter: session events
- Baileys Client → Event Listener: emits events
- Event Listener → Cloud API Output: sends webhooks
- Cloud API Output → Webhook Target: POST events
- Webhook Receiver → Incoming Service: forwards payload
- Session API → Configuration: loads config
- Session API → Session Store: reads status
- Session API → WhatsApp Adapter: starts connection
- Baileys Client → Configuration: loads config
- Baileys Client → Session Store: tracks status
- Event Listener → Data Store: stores message state
- Media API → Media Store: retrieves media
- Template API → Data Store: loads templates
- Contact API → Baileys Client: contact operation
- Registration API → Session Store: updates session
- Event Listener → Socket Broadcast: broadcasts events
- Bulk Processing → Cloud API Output: delivers payload
- Message API → Cloud API Output: reports errors