# wissa-gamma/whatsapp-bot architecture

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

## Overview

This NestJS service links a WhatsApp account, receives messages, routes private and group traffic through separate handlers, and executes eligible commands. Poll-vote updates can also trigger commands. Session status and a QR code are exposed over HTTP. The README documents session persistence and group permissions; sampled source confirms the auth-state setup and permission checks, but the implementation of unsampled capabilities is not inferred beyond that evidence.

Main entry points: [`src/bot/bot.service.ts`](https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/bot.service.ts) (Bot service), [`src/bot/handlers/private.handler.ts`](https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/handlers/private.handler.ts) (Private handler), [`src/bot/bot.controller.ts`](https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/bot.controller.ts) (Session endpoint), [`src/bot/handlers/group.handler.ts`](https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/handlers/group.handler.ts) (Group handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_connection["WhatsApp connection"]
  node_bot["Bot service<br/>[bot.service.ts]"]
  node_auth[("Auth session files<br/>[bot.service.ts]")]
end

subgraph group_routing["Message routing"]
  node_group["Group handler<br/>[group.handler.ts]"]
  node_private["Private handler<br/>[private.handler.ts]"]
  node_poll["Poll handler<br/>[poll.handler.ts]"]
  node_pollcache[("Poll cache<br/>[bot.service.ts]")]
end

subgraph group_commands["Command execution"]
  node_registry["Command registry"]
  node_commandinterface["Command interface"]
end

subgraph group_http["HTTP session API"]
  node_sessionapi["Session endpoint<br/>[bot.controller.ts]"]
  node_qrcode["QR encoder<br/>[bot.controller.ts]"]
  node_appcontroller["Root endpoint<br/>[app.controller.ts]"]
  node_appservice["Root response<br/>[app.service.ts]"]
end

node_user(("Chat participants"))
node_whatsapp(("WhatsApp"))
node_environment(("Environment config"))

node_user -->|"sends messages"| node_whatsapp
node_whatsapp -->|"delivers events"| node_bot
node_bot -->|"sends replies"| node_whatsapp
node_bot -->|"loads and saves"| node_auth
node_environment -.->|"configures groups"| node_bot
node_bot -->|"dispatches groups"| node_group
node_bot -->|"dispatches private"| node_private
node_bot -->|"dispatches poll updates"| node_poll
node_private -->|"executes command"| node_bot
node_group -->|"executes command"| node_bot
node_poll -->|"executes command"| node_bot
node_bot -->|"stores poll messages"| node_pollcache
node_private -->|"updates poll cache"| node_pollcache
node_bot -->|"looks up command"| node_registry
node_registry -->|"implements"| node_commandinterface
node_bot -->|"provides session state"| node_sessionapi
node_sessionapi -->|"encodes QR"| node_qrcode
node_user -->|"checks session"| node_sessionapi
node_appcontroller -->|"requests greeting"| node_appservice

click node_bot "https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/bot.service.ts"
click node_auth "https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/bot.service.ts"
click node_group "https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/handlers/group.handler.ts"
click node_private "https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/handlers/private.handler.ts"
click node_poll "https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/handlers/poll.handler.ts"
click node_pollcache "https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/bot.service.ts"
click node_registry "https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/commands/command.registry.ts"
click node_commandinterface "https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/commands/command.interface.ts"
click node_sessionapi "https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/bot.controller.ts"
click node_qrcode "https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/bot.controller.ts"
click node_appcontroller "https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/app.controller.ts"
click node_appservice "https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/app.service.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_bot,node_auth toneBlue
class node_group,node_private,node_poll,node_pollcache toneAmber
class node_registry,node_commandinterface toneMint
class node_sessionapi,node_qrcode,node_appcontroller,node_appservice toneRose
class node_user,node_whatsapp,node_environment toneIndigo
```

## Components

### WhatsApp connection

- [Bot service](https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/bot.service.ts): `src/bot/bot.service.ts`
- [Auth session files](https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/bot.service.ts): `src/bot/bot.service.ts`

### Message routing

- [Group handler](https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/handlers/group.handler.ts): `src/bot/handlers/group.handler.ts`
- [Private handler](https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/handlers/private.handler.ts): `src/bot/handlers/private.handler.ts`
- [Poll handler](https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/handlers/poll.handler.ts): `src/bot/handlers/poll.handler.ts`
- [Poll cache](https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/bot.service.ts): `src/bot/bot.service.ts`

### Command execution

- [Command registry](https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/commands/command.registry.ts): `src/bot/commands/command.registry.ts`
- [Command interface](https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/commands/command.interface.ts): `src/bot/commands/command.interface.ts`

### HTTP session API

- [Session endpoint](https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/bot.controller.ts): `src/bot/bot.controller.ts`
- [QR encoder](https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/bot/bot.controller.ts): `src/bot/bot.controller.ts`
- [Root endpoint](https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/app.controller.ts): `src/app.controller.ts`
- [Root response](https://github.com/wissa-gamma/whatsapp-bot/blob/main/src/app.service.ts): `src/app.service.ts`

### Other components

- **Chat participants**
- **WhatsApp**
- **Environment config**

## Connections

- Chat participants → WhatsApp: sends messages
- WhatsApp → Bot service: delivers events
- Bot service → WhatsApp: sends replies
- Bot service → Auth session files: loads and saves
- Environment config → Bot service: configures groups
- Bot service → Group handler: dispatches groups
- Bot service → Private handler: dispatches private
- Bot service → Poll handler: dispatches poll updates
- Private handler → Bot service: executes command
- Group handler → Bot service: executes command
- Poll handler → Bot service: executes command
- Bot service → Poll cache: stores poll messages
- Private handler → Poll cache: updates poll cache
- Bot service → Command registry: looks up command
- Command registry → Command interface: implements
- Bot service → Session endpoint: provides session state
- Session endpoint → QR encoder: encodes QR
- Chat participants → Session endpoint: checks session
- Root endpoint → Root response: requests greeting