# mehmetcoskun/waha architecture

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

- Interactive diagram: https://gitdiagram.com/mehmetcoskun/waha
- Repository: https://github.com/mehmetcoskun/waha

## Overview

WAHA is a self-hosted WhatsApp HTTP API. Its main workflow is to start a session, authenticate it with a QR code, then send messages and access WhatsApp data through API endpoints. Session engines connect to WhatsApp; storage and media are supporting layers. The tree also shows Chatwoot, MCP, webhook, and monitoring capabilities. Only selected source files were sampled, so some subsystem links reflect the documented workflow and module roles rather than inspected call sites.

Main entry points: [`src/core/manager.core.ts`](https://github.com/mehmetcoskun/waha/blob/core/src/core/manager.core.ts) (Session manager), [`src/core/engines`](https://github.com/mehmetcoskun/waha/tree/core/src/core/engines) (WhatsApp engines), [`src/api/chatting.controller.ts`](https://github.com/mehmetcoskun/waha/blob/core/src/api/chatting.controller.ts) (Messaging endpoints), [`src/api`](https://github.com/mehmetcoskun/waha/tree/core/src/api) (REST controllers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_rest["REST controllers"]
  node_auth["API authentication"]
  node_ws["WebSocket gateway"]
  node_sessionapi["Session endpoints"]
  node_messaging["Messaging endpoints"]
end

subgraph group_sessions["Sessions and engines"]
  node_manager["Session manager<br/>[manager.core.ts]"]
  node_session["Session runtime<br/>[session.abc.ts]"]
  node_engines["WhatsApp engines"]
end

subgraph group_state["Storage and media"]
  node_sessionstate[("Session state")]
  node_nowebstore[("NOWEB data store")]
  node_media["Media manager<br/>[MediaManager.ts]"]
  node_mediastore[("Media storage")]
end

subgraph group_integrations["Integrations"]
  node_webhooks["Webhook delivery"]
  node_chatwoot["Chatwoot integration"]
  node_apps["Apps runtime<br/>[AppRuntime.ts]"]
  node_mcp["MCP interface"]
end

subgraph group_operations["Operations"]
  node_monitoring["Metrics and health"]
  node_serverapi["Server operations"]
end

node_user(("API client"))
node_whatsapp(("WhatsApp"))

node_user -->|"authenticates"| node_auth
node_user -->|"starts session"| node_sessionapi
node_user -->|"sends requests"| node_messaging
node_user -->|"calls API"| node_rest
node_rest -->|"checks access"| node_auth
node_sessionapi -->|"manages sessions"| node_manager
node_messaging -->|"uses session"| node_manager
node_manager -->|"manages runtime"| node_session
node_session -->|"selects engine"| node_engines
node_engines -->|"connects"| node_whatsapp
node_manager -->|"persists session state"| node_sessionstate
node_engines -->|"stores WhatsApp data"| node_nowebstore
node_messaging -->|"handles media"| node_media
node_media -->|"reads and writes"| node_mediastore
node_engines -->|"emits events"| node_webhooks
node_engines -->|"supplies WhatsApp events"| node_chatwoot
node_chatwoot -->|"syncs conversations"| node_whatsapp
node_apps -->|"uses sessions"| node_manager
node_mcp -.->|"exposes API tools"| node_rest
node_monitoring -.->|"collects session metrics"| node_manager
node_user -->|"queries operations"| node_serverapi
node_user -->|"opens connection"| node_ws

click node_rest "https://github.com/mehmetcoskun/waha/tree/core/src/api"
click node_auth "https://github.com/mehmetcoskun/waha/tree/core/src/core/auth"
click node_ws "https://github.com/mehmetcoskun/waha/blob/core/src/api/websocket.gateway.core.ts"
click node_sessionapi "https://github.com/mehmetcoskun/waha/blob/core/src/api/sessions.controller.ts"
click node_messaging "https://github.com/mehmetcoskun/waha/blob/core/src/api/chatting.controller.ts"
click node_manager "https://github.com/mehmetcoskun/waha/blob/core/src/core/manager.core.ts"
click node_session "https://github.com/mehmetcoskun/waha/blob/core/src/core/abc/session.abc.ts"
click node_engines "https://github.com/mehmetcoskun/waha/tree/core/src/core/engines"
click node_sessionstate "https://github.com/mehmetcoskun/waha/tree/core/src/core/storage"
click node_nowebstore "https://github.com/mehmetcoskun/waha/tree/core/src/core/engines/noweb/store"
click node_media "https://github.com/mehmetcoskun/waha/blob/core/src/core/media/MediaManager.ts"
click node_mediastore "https://github.com/mehmetcoskun/waha/tree/core/src/core/media"
click node_webhooks "https://github.com/mehmetcoskun/waha/tree/core/src/modules/waha-webhook"
click node_chatwoot "https://github.com/mehmetcoskun/waha/tree/core/src/apps/chatwoot"
click node_apps "https://github.com/mehmetcoskun/waha/blob/core/src/apps/app_sdk/apps/AppRuntime.ts"
click node_mcp "https://github.com/mehmetcoskun/waha/tree/core/src/apps/mcp"
click node_monitoring "https://github.com/mehmetcoskun/waha/tree/core/src/modules/waha-prometheus"
click node_serverapi "https://github.com/mehmetcoskun/waha/blob/core/src/api/server.controller.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_rest,node_auth,node_ws,node_sessionapi,node_messaging,node_user toneBlue
class node_manager,node_session,node_engines toneAmber
class node_sessionstate,node_nowebstore,node_media,node_mediastore toneMint
class node_webhooks,node_chatwoot,node_apps,node_mcp toneRose
class node_monitoring,node_serverapi,node_whatsapp toneIndigo
```

## Components

### HTTP API

- [REST controllers](https://github.com/mehmetcoskun/waha/tree/core/src/api): `src/api`
- [API authentication](https://github.com/mehmetcoskun/waha/tree/core/src/core/auth): `src/core/auth`
- [WebSocket gateway](https://github.com/mehmetcoskun/waha/blob/core/src/api/websocket.gateway.core.ts): `src/api/websocket.gateway.core.ts`
- [Session endpoints](https://github.com/mehmetcoskun/waha/blob/core/src/api/sessions.controller.ts): `src/api/sessions.controller.ts`
- [Messaging endpoints](https://github.com/mehmetcoskun/waha/blob/core/src/api/chatting.controller.ts): `src/api/chatting.controller.ts`

### Sessions and engines

- [Session manager](https://github.com/mehmetcoskun/waha/blob/core/src/core/manager.core.ts): `src/core/manager.core.ts`
- [Session runtime](https://github.com/mehmetcoskun/waha/blob/core/src/core/abc/session.abc.ts): `src/core/abc/session.abc.ts`
- [WhatsApp engines](https://github.com/mehmetcoskun/waha/tree/core/src/core/engines): `src/core/engines`

### Storage and media

- [Session state](https://github.com/mehmetcoskun/waha/tree/core/src/core/storage): `src/core/storage`
- [NOWEB data store](https://github.com/mehmetcoskun/waha/tree/core/src/core/engines/noweb/store): `src/core/engines/noweb/store`
- [Media manager](https://github.com/mehmetcoskun/waha/blob/core/src/core/media/MediaManager.ts): `src/core/media/MediaManager.ts`
- [Media storage](https://github.com/mehmetcoskun/waha/tree/core/src/core/media): `src/core/media`

### Integrations

- [Webhook delivery](https://github.com/mehmetcoskun/waha/tree/core/src/modules/waha-webhook): `src/modules/waha-webhook`
- [Chatwoot integration](https://github.com/mehmetcoskun/waha/tree/core/src/apps/chatwoot): `src/apps/chatwoot`
- [Apps runtime](https://github.com/mehmetcoskun/waha/blob/core/src/apps/app_sdk/apps/AppRuntime.ts): `src/apps/app_sdk/apps/AppRuntime.ts`
- [MCP interface](https://github.com/mehmetcoskun/waha/tree/core/src/apps/mcp): `src/apps/mcp`

### Operations

- [Metrics and health](https://github.com/mehmetcoskun/waha/tree/core/src/modules/waha-prometheus): `src/modules/waha-prometheus`
- [Server operations](https://github.com/mehmetcoskun/waha/blob/core/src/api/server.controller.ts): `src/api/server.controller.ts`

### Other components

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

## Connections

- API client → API authentication: authenticates
- API client → Session endpoints: starts session
- API client → Messaging endpoints: sends requests
- API client → REST controllers: calls API
- REST controllers → API authentication: checks access
- Session endpoints → Session manager: manages sessions
- Messaging endpoints → Session manager: uses session
- Session manager → Session runtime: manages runtime
- Session runtime → WhatsApp engines: selects engine
- WhatsApp engines → WhatsApp: connects
- Session manager → Session state: persists session state
- WhatsApp engines → NOWEB data store: stores WhatsApp data
- Messaging endpoints → Media manager: handles media
- Media manager → Media storage: reads and writes
- WhatsApp engines → Webhook delivery: emits events
- WhatsApp engines → Chatwoot integration: supplies WhatsApp events
- Chatwoot integration → WhatsApp: syncs conversations
- Apps runtime → Session manager: uses sessions
- MCP interface → REST controllers: exposes API tools
- Metrics and health → Session manager: collects session metrics
- API client → Server operations: queries operations
- API client → WebSocket gateway: opens connection