# wppconnect-team/wppconnect-server architecture

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

- Interactive diagram: https://gitdiagram.com/wppconnect-team/wppconnect-server
- Repository: https://github.com/wppconnect-team/wppconnect-server

## Overview

WPPConnect Server exposes a session-scoped REST API around the WPPConnect WhatsApp automation library, with a Manager UI and real-time events. Users create or pair sessions, then invoke messaging, device, group, contact, catalog and related operations; session events can be delivered through webhooks or Manager sockets. The graph highlights those domain stages and token persistence. Some feature controllers and integrations are represented at their exact directories because their implementations were not sampled; their existence and route dispatch are documented by the route index and README.

Main entry points: [`src/routes/index.ts`](https://github.com/wppconnect-team/wppconnect-server/blob/main/src/routes/index.ts) (API Routes), [`src/controller/sessionController.ts`](https://github.com/wppconnect-team/wppconnect-server/blob/main/src/controller/sessionController.ts) (Session API), [`src/util/createSessionUtil.ts`](https://github.com/wppconnect-team/wppconnect-server/blob/main/src/util/createSessionUtil.ts) (Session Creation), [`src/index.ts`](https://github.com/wppconnect-team/wppconnect-server/blob/main/src/index.ts) (HTTP Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["HTTP and Manager"]
  node_server["HTTP Server<br/>[index.ts]"]
  node_api_routes["API Routes<br/>[index.ts]"]
  node_manager["Manager UI and Routes<br/>[routes.ts]"]
  node_manager_auth["Manager Authorization<br/>[auth.ts]"]
  node_manager_socket["Manager Events<br/>[socket.ts]"]
end

subgraph group_sessions["Session Runtime"]
  node_session_api["Session API"]
  node_session_creator["Session Creation"]
  node_session_registry["Session Registry<br/>[sessionUtil.ts]"]
  node_session_maintenance["Session Maintenance"]
end

subgraph group_operations["WhatsApp Operations"]
  node_message_ops["Messaging"]
  node_device_ops["Device and Chats"]
  node_group_ops["Groups<br/>[groupController.ts]"]
  node_catalog_ops["Product Catalog"]
  node_other_ops["Contacts and Features"]
end

subgraph group_state["Persistence and Integrations"]
  node_token_factory["Token Store Factory<br/>[factory.ts]"]
  node_token_store[("Token Stores")]
  node_webhook_support["Webhook Utilities<br/>[functions.ts]"]
  node_chatwoot["Chatwoot Client<br/>[chatWootClient.ts]"]
  node_config["Server Configuration<br/>[config.ts]"]
end

node_integrator(("API Integrator"))
node_whatsapp["WPPConnect Library"]

node_integrator -->|"calls API"| node_server
node_server -->|"mounts routes"| node_api_routes
node_server -->|"mounts routes"| node_manager
node_manager -->|"checks access"| node_manager_auth
node_api_routes -->|"dispatches sessions"| node_session_api
node_api_routes -->|"dispatches messages"| node_message_ops
node_api_routes -->|"dispatches device actions"| node_device_ops
node_api_routes -->|"dispatches group actions"| node_group_ops
node_api_routes -->|"dispatches catalog actions"| node_catalog_ops
node_api_routes -->|"dispatches features"| node_other_ops
node_session_api -->|"creates sessions"| node_session_creator
node_session_api -->|"cleans sessions"| node_session_registry
node_session_creator -->|"creates client"| node_whatsapp
node_session_creator -->|"emits events"| node_manager_socket
node_session_creator -->|"sends event hooks"| node_webhook_support
node_session_creator -->|"initializes client"| node_chatwoot
node_manager -->|"loads tokens"| node_token_factory
node_token_factory -->|"selects store"| node_token_store
node_session_api -->|"lists tokens"| node_token_factory
node_server -->|"loads options"| node_config
node_session_api -->|"checks maintenance"| node_session_maintenance
node_integrator -->|"administers sessions"| node_manager
node_whatsapp -.->|"sends messages"| node_integrator

click node_server "https://github.com/wppconnect-team/wppconnect-server/blob/main/src/index.ts"
click node_api_routes "https://github.com/wppconnect-team/wppconnect-server/blob/main/src/routes/index.ts"
click node_manager "https://github.com/wppconnect-team/wppconnect-server/blob/main/src/manager/routes.ts"
click node_manager_auth "https://github.com/wppconnect-team/wppconnect-server/blob/main/src/manager/auth.ts"
click node_manager_socket "https://github.com/wppconnect-team/wppconnect-server/blob/main/src/manager/socket.ts"
click node_session_api "https://github.com/wppconnect-team/wppconnect-server/blob/main/src/controller/sessionController.ts"
click node_session_creator "https://github.com/wppconnect-team/wppconnect-server/blob/main/src/util/createSessionUtil.ts"
click node_session_registry "https://github.com/wppconnect-team/wppconnect-server/blob/main/src/util/sessionUtil.ts"
click node_session_maintenance "https://github.com/wppconnect-team/wppconnect-server/blob/main/src/util/sessionMaintenance.ts"
click node_message_ops "https://github.com/wppconnect-team/wppconnect-server/blob/main/src/controller/messageController.ts"
click node_device_ops "https://github.com/wppconnect-team/wppconnect-server/blob/main/src/controller/deviceController.ts"
click node_group_ops "https://github.com/wppconnect-team/wppconnect-server/blob/main/src/controller/groupController.ts"
click node_catalog_ops "https://github.com/wppconnect-team/wppconnect-server/blob/main/src/controller/catalogController.ts"
click node_other_ops "https://github.com/wppconnect-team/wppconnect-server/tree/main/src/controller"
click node_token_factory "https://github.com/wppconnect-team/wppconnect-server/blob/main/src/util/tokenStore/factory.ts"
click node_token_store "https://github.com/wppconnect-team/wppconnect-server/tree/main/src/util/tokenStore"
click node_webhook_support "https://github.com/wppconnect-team/wppconnect-server/blob/main/src/util/functions.ts"
click node_chatwoot "https://github.com/wppconnect-team/wppconnect-server/blob/main/src/util/chatWootClient.ts"
click node_config "https://github.com/wppconnect-team/wppconnect-server/blob/main/src/config.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_server,node_api_routes,node_manager,node_manager_auth,node_manager_socket toneBlue
class node_session_api,node_session_creator,node_session_registry,node_session_maintenance toneAmber
class node_message_ops,node_device_ops,node_group_ops,node_catalog_ops,node_other_ops,node_integrator toneMint
class node_token_factory,node_token_store,node_webhook_support,node_chatwoot,node_config toneRose
class node_whatsapp toneIndigo
```

## Components

### HTTP and Manager

- [HTTP Server](https://github.com/wppconnect-team/wppconnect-server/blob/main/src/index.ts): `src/index.ts`
- [API Routes](https://github.com/wppconnect-team/wppconnect-server/blob/main/src/routes/index.ts): `src/routes/index.ts`
- [Manager UI and Routes](https://github.com/wppconnect-team/wppconnect-server/blob/main/src/manager/routes.ts): `src/manager/routes.ts`
- [Manager Authorization](https://github.com/wppconnect-team/wppconnect-server/blob/main/src/manager/auth.ts): `src/manager/auth.ts`
- [Manager Events](https://github.com/wppconnect-team/wppconnect-server/blob/main/src/manager/socket.ts): `src/manager/socket.ts`

### Session Runtime

- [Session API](https://github.com/wppconnect-team/wppconnect-server/blob/main/src/controller/sessionController.ts): `src/controller/sessionController.ts`
- [Session Creation](https://github.com/wppconnect-team/wppconnect-server/blob/main/src/util/createSessionUtil.ts): `src/util/createSessionUtil.ts`
- [Session Registry](https://github.com/wppconnect-team/wppconnect-server/blob/main/src/util/sessionUtil.ts): `src/util/sessionUtil.ts`
- [Session Maintenance](https://github.com/wppconnect-team/wppconnect-server/blob/main/src/util/sessionMaintenance.ts): `src/util/sessionMaintenance.ts`

### WhatsApp Operations

- [Messaging](https://github.com/wppconnect-team/wppconnect-server/blob/main/src/controller/messageController.ts): `src/controller/messageController.ts`
- [Device and Chats](https://github.com/wppconnect-team/wppconnect-server/blob/main/src/controller/deviceController.ts): `src/controller/deviceController.ts`
- [Groups](https://github.com/wppconnect-team/wppconnect-server/blob/main/src/controller/groupController.ts): `src/controller/groupController.ts`
- [Product Catalog](https://github.com/wppconnect-team/wppconnect-server/blob/main/src/controller/catalogController.ts): `src/controller/catalogController.ts`
- [Contacts and Features](https://github.com/wppconnect-team/wppconnect-server/tree/main/src/controller): `src/controller`

### Persistence and Integrations

- [Token Store Factory](https://github.com/wppconnect-team/wppconnect-server/blob/main/src/util/tokenStore/factory.ts): `src/util/tokenStore/factory.ts`
- [Token Stores](https://github.com/wppconnect-team/wppconnect-server/tree/main/src/util/tokenStore): `src/util/tokenStore`
- [Webhook Utilities](https://github.com/wppconnect-team/wppconnect-server/blob/main/src/util/functions.ts): `src/util/functions.ts`
- [Chatwoot Client](https://github.com/wppconnect-team/wppconnect-server/blob/main/src/util/chatWootClient.ts): `src/util/chatWootClient.ts`
- [Server Configuration](https://github.com/wppconnect-team/wppconnect-server/blob/main/src/config.ts): `src/config.ts`

### Other components

- **API Integrator**
- **WPPConnect Library**

## Connections

- API Integrator → HTTP Server: calls API (evidence: `README.md`)
- HTTP Server → API Routes: mounts routes (evidence: `src/index.ts`)
- HTTP Server → Manager UI and Routes: mounts routes (evidence: `src/index.ts`)
- Manager UI and Routes → Manager Authorization: checks access (evidence: `src/manager/routes.ts`)
- API Routes → Session API: dispatches sessions (evidence: `src/routes/index.ts`)
- API Routes → Messaging: dispatches messages (evidence: `src/routes/index.ts`)
- API Routes → Device and Chats: dispatches device actions (evidence: `src/routes/index.ts`)
- API Routes → Groups: dispatches group actions (evidence: `src/routes/index.ts`)
- API Routes → Product Catalog: dispatches catalog actions (evidence: `src/routes/index.ts`)
- API Routes → Contacts and Features: dispatches features (evidence: `src/routes/index.ts`)
- Session API → Session Creation: creates sessions (evidence: `src/controller/sessionController.ts`)
- Session API → Session Registry: cleans sessions (evidence: `src/controller/sessionController.ts`)
- Session Creation → WPPConnect Library: creates client (evidence: `src/util/createSessionUtil.ts`)
- Session Creation → Manager Events: emits events (evidence: `src/util/createSessionUtil.ts`)
- Session Creation → Webhook Utilities: sends event hooks (evidence: `src/util/createSessionUtil.ts`)
- Session Creation → Chatwoot Client: initializes client (evidence: `src/util/createSessionUtil.ts`)
- Manager UI and Routes → Token Store Factory: loads tokens (evidence: `src/manager/routes.ts`)
- Token Store Factory → Token Stores: selects store (evidence: `src/util/tokenStore/factory.ts`)
- Session API → Token Store Factory: lists tokens (evidence: `src/controller/sessionController.ts`)
- HTTP Server → Server Configuration: loads options (evidence: `src/index.ts`)
- Session API → Session Maintenance: checks maintenance (evidence: `src/controller/sessionController.ts`)
- API Integrator → Manager UI and Routes: administers sessions (evidence: `README.md`)
- WPPConnect Library → API Integrator: sends messages
