# punith-bot/whatsapp-ai-bot architecture

> Architecture diagram of the GitHub repository punith-bot/whatsapp-ai-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/punith-bot/whatsapp-ai-bot
- Repository: https://github.com/punith-bot/whatsapp-ai-bot

## Overview

WhatsApp AI Bot receives contact messages through its WhatsApp client, routes them through message handling and per-contact throttling, and replies using AI with conversation context, document parsing, or web search as appropriate. SQLite stores contacts, settings, and conversation state; a local dashboard controls the bot and connection, while bot profiles and scheduling add autonomous behavior. The runtime and desktop shell provide startup and lifecycle management. Some capabilities are documented but their implementation was not sampled; those links are omitted where ownership is uncertain.

Main entry points: [`src/server.js`](https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/server.js) (Dashboard API), [`src/handler.js`](https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/handler.js) (Message Handler), [`src/bot.js`](https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/bot.js) (WhatsApp Client), [`src/runtime.js`](https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/runtime.js) (Runtime Lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime & Desktop"]
  node_entry["CLI Entry<br/>[index.js]"]
  node_desktop["Desktop Shell<br/>[main.js]"]
  node_runtime_core["Runtime Lifecycle<br/>[runtime.js]"]
  node_config["Environment Config<br/>[config.js]"]
  node_desktop_preload["Desktop Preload<br/>[preload.js]"]
end

subgraph group_messaging["WhatsApp Messaging"]
  node_wa_client["WhatsApp Client<br/>[bot.js]"]
  node_handler["Message Handler<br/>[handler.js]"]
  node_queue["Contact Queue<br/>[queue.js]"]
  node_bot_mode["Profiles &amp; Scheduling<br/>[bot-mode.js]"]
end

subgraph group_intelligence["AI &amp; Content"]
  node_ai["AI Reply Engine<br/>[ai.js]"]
  node_documents["Document Parsing<br/>[documents.js]"]
  node_search["Search Detection<br/>[search.js]"]
end

subgraph group_state["Data &amp; State"]
  node_database[("SQLite Store<br/>[database.js]")]
end

subgraph group_control["Dashboard &amp; Controls"]
  node_server["Dashboard API<br/>[server.js]"]
  node_socket["Live Events &amp; QR<br/>[socket.js]"]
  node_dashboard["Dashboard UI<br/>[app.js]"]
end

node_user(("Owner"))
node_contact(("WhatsApp Contact"))
node_whatsapp["WhatsApp"]
node_groq["Groq API"]

node_entry -->|"starts"| node_runtime_core
node_desktop -->|"starts"| node_runtime_core
node_runtime_core -->|"validates"| node_config
node_runtime_core -->|"loads"| node_database
node_runtime_core -->|"loads"| node_server
node_runtime_core -->|"loads"| node_wa_client
node_contact -.->|"sends messages"| node_whatsapp
node_whatsapp -.->|"delivers messages"| node_wa_client
node_wa_client -->|"routes messages"| node_handler
node_handler -->|"enqueues work"| node_queue
node_handler -->|"parses instructions"| node_bot_mode
node_handler -->|"reads and writes"| node_database
node_handler -->|"parses attachments"| node_documents
node_handler -->|"generates replies"| node_ai
node_ai -->|"checks search need"| node_search
node_ai -->|"reads config"| node_database
node_ai -.->|"requests completions"| node_groq
node_handler -.->|"sends replies"| node_wa_client
node_wa_client -->|"syncs contacts"| node_database
node_wa_client -->|"emits status"| node_socket
node_bot_mode -->|"manages profiles"| node_database
node_bot_mode -->|"generates proposals"| node_ai
node_bot_mode -->|"emits updates"| node_socket
node_server -->|"serves data"| node_database
node_server -->|"serves controls"| node_bot_mode
node_server -->|"resets session"| node_wa_client
node_server -.->|"configures events"| node_socket
node_server -->|"serves AI settings"| node_ai
node_user -->|"uses controls"| node_dashboard
node_dashboard -->|"calls API"| node_server
node_server -->|"serves dashboard"| node_dashboard
node_socket -.->|"streams events"| node_dashboard
node_desktop -.->|"exposes bridge"| node_desktop_preload

click node_entry "https://github.com/punith-bot/whatsapp-ai-bot/blob/main/index.js"
click node_desktop "https://github.com/punith-bot/whatsapp-ai-bot/blob/main/desktop/main.js"
click node_runtime_core "https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/runtime.js"
click node_config "https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/config.js"
click node_wa_client "https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/bot.js"
click node_handler "https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/handler.js"
click node_queue "https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/queue.js"
click node_bot_mode "https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/bot-mode.js"
click node_ai "https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/ai.js"
click node_documents "https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/documents.js"
click node_search "https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/search.js"
click node_database "https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/database.js"
click node_server "https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/server.js"
click node_socket "https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/socket.js"
click node_dashboard "https://github.com/punith-bot/whatsapp-ai-bot/blob/main/dashboard/app.js"
click node_desktop_preload "https://github.com/punith-bot/whatsapp-ai-bot/blob/main/desktop/preload.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_entry,node_desktop,node_runtime_core,node_config,node_desktop_preload toneBlue
class node_wa_client,node_handler,node_queue,node_bot_mode toneAmber
class node_ai,node_documents,node_search,node_groq toneMint
class node_database toneRose
class node_server,node_socket,node_dashboard,node_user,node_contact,node_whatsapp toneIndigo
```

## Components

### Runtime & Desktop

- [CLI Entry](https://github.com/punith-bot/whatsapp-ai-bot/blob/main/index.js): `index.js`
- [Desktop Shell](https://github.com/punith-bot/whatsapp-ai-bot/blob/main/desktop/main.js): `desktop/main.js`
- [Runtime Lifecycle](https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/runtime.js): `src/runtime.js`
- [Environment Config](https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/config.js): `src/config.js`
- [Desktop Preload](https://github.com/punith-bot/whatsapp-ai-bot/blob/main/desktop/preload.js): `desktop/preload.js`

### WhatsApp Messaging

- [WhatsApp Client](https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/bot.js): `src/bot.js`
- [Message Handler](https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/handler.js): `src/handler.js`
- [Contact Queue](https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/queue.js): `src/queue.js`
- [Profiles & Scheduling](https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/bot-mode.js): `src/bot-mode.js`

### AI & Content

- [AI Reply Engine](https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/ai.js): `src/ai.js`
- [Document Parsing](https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/documents.js): `src/documents.js`
- [Search Detection](https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/search.js): `src/search.js`

### Data & State

- [SQLite Store](https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/database.js): `src/database.js`

### Dashboard & Controls

- [Dashboard API](https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/server.js): `src/server.js`
- [Live Events & QR](https://github.com/punith-bot/whatsapp-ai-bot/blob/main/src/socket.js): `src/socket.js`
- [Dashboard UI](https://github.com/punith-bot/whatsapp-ai-bot/blob/main/dashboard/app.js): `dashboard/app.js`

### Other components

- **Owner**
- **WhatsApp Contact**
- **WhatsApp**
- **Groq API**

## Connections

- CLI Entry → Runtime Lifecycle: starts (evidence: `index.js`)
- Desktop Shell → Runtime Lifecycle: starts (evidence: `desktop/main.js`)
- Runtime Lifecycle → Environment Config: validates (evidence: `src/runtime.js`)
- Runtime Lifecycle → SQLite Store: loads (evidence: `src/runtime.js`)
- Runtime Lifecycle → Dashboard API: loads (evidence: `src/runtime.js`)
- Runtime Lifecycle → WhatsApp Client: loads (evidence: `src/runtime.js`)
- WhatsApp Contact → WhatsApp: sends messages (evidence: `README.md`)
- WhatsApp → WhatsApp Client: delivers messages (evidence: `README.md`)
- WhatsApp Client → Message Handler: routes messages (evidence: `src/bot.js`)
- Message Handler → Contact Queue: enqueues work (evidence: `src/handler.js`)
- Message Handler → Profiles & Scheduling: parses instructions (evidence: `src/handler.js`)
- Message Handler → SQLite Store: reads and writes (evidence: `src/handler.js`)
- Message Handler → Document Parsing: parses attachments (evidence: `src/handler.js`)
- Message Handler → AI Reply Engine: generates replies (evidence: `src/handler.js`)
- AI Reply Engine → Search Detection: checks search need (evidence: `src/ai.js`)
- AI Reply Engine → SQLite Store: reads config (evidence: `src/ai.js`)
- AI Reply Engine → Groq API: requests completions (evidence: `README.md`)
- Message Handler → WhatsApp Client: sends replies (evidence: `src/handler.js`)
- WhatsApp Client → SQLite Store: syncs contacts (evidence: `src/bot.js`)
- WhatsApp Client → Live Events & QR: emits status (evidence: `src/bot.js`)
- Profiles & Scheduling → SQLite Store: manages profiles (evidence: `src/bot-mode.js`)
- Profiles & Scheduling → AI Reply Engine: generates proposals (evidence: `src/bot-mode.js`)
- Profiles & Scheduling → Live Events & QR: emits updates (evidence: `src/bot-mode.js`)
- Dashboard API → SQLite Store: serves data (evidence: `src/server.js`)
- Dashboard API → Profiles & Scheduling: serves controls (evidence: `src/server.js`)
- Dashboard API → WhatsApp Client: resets session (evidence: `src/server.js`)
- Dashboard API → Live Events & QR: configures events (evidence: `src/socket.js`)
- Dashboard API → AI Reply Engine: serves AI settings (evidence: `src/server.js`)
- Owner → Dashboard UI: uses controls (evidence: `README.md`)
- Dashboard UI → Dashboard API: calls API (evidence: `README.md`)
- Dashboard API → Dashboard UI: serves dashboard (evidence: `src/server.js`)
- Live Events & QR → Dashboard UI: streams events (evidence: `src/socket.js`)
- Desktop Shell → Desktop Preload: exposes bridge (evidence: `desktop/main.js`)