# chrishubert/whatsapp-api architecture

> Architecture diagram of the GitHub repository chrishubert/whatsapp-api, 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/chrishubert/whatsapp-api
- Repository: https://github.com/chrishubert/whatsapp-api

## Overview

WhatsApp REST API wraps whatsapp-web.js, letting clients manage named WhatsApp sessions and perform messaging, chat, contact, and group operations over HTTP. The main flow is an API request through Express routing and session validation to a controller, which invokes the session’s WhatsApp client and returns a result. Session lifecycle and local authentication support restoration; client events can dispatch configurable webhook callbacks. The graph reflects the sampled controllers and session code plus README capabilities; unsampled route and event wiring is represented only where documented.

Main entry points: [`src/sessions.js`](https://github.com/chrishubert/whatsapp-api/blob/master/src/sessions.js) (Session Runtime), [`src/routes.js`](https://github.com/chrishubert/whatsapp-api/blob/master/src/routes.js) (API Routes), [`src/app.js`](https://github.com/chrishubert/whatsapp-api/blob/master/src/app.js) (Express App), [`src/controllers/sessionController.js`](https://github.com/chrishubert/whatsapp-api/blob/master/src/controllers/sessionController.js) (Session API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_app["Express App<br/>[app.js]"]
  node_routes["API Routes<br/>[routes.js]"]
  node_middleware["Request Middleware<br/>[middleware.js]"]
  node_session_controller["Session API"]
  node_health["Health API"]
end

subgraph group_session["Session Runtime"]
  node_session_runtime["Session Runtime<br/>[sessions.js]"]
  node_session_store[("Local Session Data<br/>[sessions.js]")]
  node_config["Runtime Config<br/>[config.js]"]
end

subgraph group_operations["WhatsApp Operations"]
  node_client_controller["Client Operations"]
  node_chat_controller["Chat Operations<br/>[chatController.js]"]
  node_message_controller["Message Operations"]
  node_contact_controller["Contact Operations"]
  node_group_controller["Group Operations"]
end

subgraph group_integration["External Integrations"]
  node_utils["Callback Utilities<br/>[utils.js]"]
  node_whatsapp["WhatsApp Web"]
end

node_consumer(("API Consumer"))
node_webhook["Webhook Endpoint"]
node_qr_user(("WhatsApp User"))

node_consumer -->|"sends requests"| node_app
node_app -->|"mounts routes"| node_routes
node_routes -->|"validates requests"| node_middleware
node_routes -->|"dispatches session"| node_session_controller
node_routes -->|"dispatches health"| node_health
node_routes -->|"dispatches client"| node_client_controller
node_routes -->|"dispatches chat"| node_chat_controller
node_routes -->|"dispatches message"| node_message_controller
node_routes -->|"dispatches contact"| node_contact_controller
node_routes -->|"dispatches group"| node_group_controller
node_app -->|"restores sessions"| node_session_runtime
node_session_controller -->|"manages sessions"| node_session_runtime
node_session_controller -->|"reads QR state"| node_session_store
node_session_runtime -->|"persists auth"| node_session_store
node_session_runtime -->|"reads settings"| node_config
node_client_controller -->|"gets session client"| node_session_runtime
node_chat_controller -->|"gets session client"| node_session_runtime
node_message_controller -->|"gets session client"| node_session_runtime
node_contact_controller -->|"gets session client"| node_session_runtime
node_group_controller -->|"gets session client"| node_session_runtime
node_session_runtime -->|"initializes client"| node_whatsapp
node_client_controller -->|"invokes client API"| node_whatsapp
node_chat_controller -->|"invokes chat API"| node_whatsapp
node_message_controller -->|"invokes message API"| node_whatsapp
node_contact_controller -->|"invokes contact API"| node_whatsapp
node_group_controller -->|"invokes group API"| node_whatsapp
node_qr_user -->|"scans QR"| node_whatsapp
node_session_runtime -->|"triggers callbacks"| node_utils
node_utils -->|"posts events"| node_webhook

click node_app "https://github.com/chrishubert/whatsapp-api/blob/master/src/app.js"
click node_routes "https://github.com/chrishubert/whatsapp-api/blob/master/src/routes.js"
click node_middleware "https://github.com/chrishubert/whatsapp-api/blob/master/src/middleware.js"
click node_session_controller "https://github.com/chrishubert/whatsapp-api/blob/master/src/controllers/sessionController.js"
click node_health "https://github.com/chrishubert/whatsapp-api/blob/master/src/controllers/healthController.js"
click node_client_controller "https://github.com/chrishubert/whatsapp-api/blob/master/src/controllers/clientController.js"
click node_chat_controller "https://github.com/chrishubert/whatsapp-api/blob/master/src/controllers/chatController.js"
click node_message_controller "https://github.com/chrishubert/whatsapp-api/blob/master/src/controllers/messageController.js"
click node_contact_controller "https://github.com/chrishubert/whatsapp-api/blob/master/src/controllers/contactController.js"
click node_group_controller "https://github.com/chrishubert/whatsapp-api/blob/master/src/controllers/groupChatController.js"
click node_session_runtime "https://github.com/chrishubert/whatsapp-api/blob/master/src/sessions.js"
click node_session_store "https://github.com/chrishubert/whatsapp-api/blob/master/src/sessions.js"
click node_config "https://github.com/chrishubert/whatsapp-api/blob/master/src/config.js"
click node_utils "https://github.com/chrishubert/whatsapp-api/blob/master/src/utils.js"

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_routes,node_middleware,node_session_controller,node_health,node_qr_user toneBlue
class node_session_runtime,node_session_store,node_config toneAmber
class node_client_controller,node_chat_controller,node_message_controller,node_contact_controller,node_group_controller,node_consumer,node_webhook toneMint
class node_utils,node_whatsapp toneRose
```

## Components

### HTTP API

- [Express App](https://github.com/chrishubert/whatsapp-api/blob/master/src/app.js): `src/app.js`
- [API Routes](https://github.com/chrishubert/whatsapp-api/blob/master/src/routes.js): `src/routes.js`
- [Request Middleware](https://github.com/chrishubert/whatsapp-api/blob/master/src/middleware.js): `src/middleware.js`
- [Session API](https://github.com/chrishubert/whatsapp-api/blob/master/src/controllers/sessionController.js): `src/controllers/sessionController.js`
- [Health API](https://github.com/chrishubert/whatsapp-api/blob/master/src/controllers/healthController.js): `src/controllers/healthController.js`

### Session Runtime

- [Session Runtime](https://github.com/chrishubert/whatsapp-api/blob/master/src/sessions.js): `src/sessions.js`
- [Local Session Data](https://github.com/chrishubert/whatsapp-api/blob/master/src/sessions.js): `src/sessions.js`
- [Runtime Config](https://github.com/chrishubert/whatsapp-api/blob/master/src/config.js): `src/config.js`

### WhatsApp Operations

- [Client Operations](https://github.com/chrishubert/whatsapp-api/blob/master/src/controllers/clientController.js): `src/controllers/clientController.js`
- [Chat Operations](https://github.com/chrishubert/whatsapp-api/blob/master/src/controllers/chatController.js): `src/controllers/chatController.js`
- [Message Operations](https://github.com/chrishubert/whatsapp-api/blob/master/src/controllers/messageController.js): `src/controllers/messageController.js`
- [Contact Operations](https://github.com/chrishubert/whatsapp-api/blob/master/src/controllers/contactController.js): `src/controllers/contactController.js`
- [Group Operations](https://github.com/chrishubert/whatsapp-api/blob/master/src/controllers/groupChatController.js): `src/controllers/groupChatController.js`

### External Integrations

- [Callback Utilities](https://github.com/chrishubert/whatsapp-api/blob/master/src/utils.js): `src/utils.js`
- **WhatsApp Web**

### Other components

- **API Consumer**
- **Webhook Endpoint**
- **WhatsApp User**

## Connections

- API Consumer → Express App: sends requests
- Express App → API Routes: mounts routes
- API Routes → Request Middleware: validates requests
- API Routes → Session API: dispatches session
- API Routes → Health API: dispatches health
- API Routes → Client Operations: dispatches client
- API Routes → Chat Operations: dispatches chat
- API Routes → Message Operations: dispatches message
- API Routes → Contact Operations: dispatches contact
- API Routes → Group Operations: dispatches group
- Express App → Session Runtime: restores sessions
- Session API → Session Runtime: manages sessions
- Session API → Local Session Data: reads QR state
- Session Runtime → Local Session Data: persists auth
- Session Runtime → Runtime Config: reads settings
- Client Operations → Session Runtime: gets session client
- Chat Operations → Session Runtime: gets session client
- Message Operations → Session Runtime: gets session client
- Contact Operations → Session Runtime: gets session client
- Group Operations → Session Runtime: gets session client
- Session Runtime → WhatsApp Web: initializes client
- Client Operations → WhatsApp Web: invokes client API
- Chat Operations → WhatsApp Web: invokes chat API
- Message Operations → WhatsApp Web: invokes message API
- Contact Operations → WhatsApp Web: invokes contact API
- Group Operations → WhatsApp Web: invokes group API
- WhatsApp User → WhatsApp Web: scans QR
- Session Runtime → Callback Utilities: triggers callbacks
- Callback Utilities → Webhook Endpoint: posts events