# techify-one/whatsbot-lite architecture

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

- Interactive diagram: https://gitdiagram.com/techify-one/whatsbot-lite
- Repository: https://github.com/techify-one/whatsbot-lite

## Overview

WhatsBot-Lite is a locally run WhatsApp AI assistant with a browser-based operator panel. The main workflow receives WhatsApp messages through the webhook, processes messages and intent-related work, and sends replies through GOWA; operators also manage conversations and configuration in the panel. Persistence, plugins, portability, and AI configuration are distinct supporting capabilities. Some backend routing is supported by the SOURCE INDEX, while unsampled routes and frontend-to-backend wiring are left unverified rather than inferred.

Main entry points: [`server/routes/webhook.py`](https://github.com/techify-one/whatsbot-lite/blob/main/server/routes/webhook.py) (Message webhook), [`agent/handler.py`](https://github.com/techify-one/whatsbot-lite/blob/main/agent/handler.py) (Agent handler), [`plugins/context.py`](https://github.com/techify-one/whatsbot-lite/blob/main/plugins/context.py) (Plugin system), [`gowa/client.py`](https://github.com/techify-one/whatsbot-lite/blob/main/gowa/client.py) (GOWA client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Conversation automation"]
  node_gowa["GOWA client<br/>[client.py]"]
  node_webhook["Message webhook<br/>[webhook.py]"]
  node_handler["Agent handler<br/>[handler.py]"]
  node_ai_engine["AI engine<br/>[agno_engine.py]"]
  node_agent_factory["Agent assembly<br/>[agent_factory.py]"]
  node_intents["Intent runtime<br/>[intent_runtime.py]"]
  node_mentions["Group mentions<br/>[group_mentions.py]"]
  node_memory["Contact memory<br/>[memory.py]"]
end

subgraph group_platform["Web platform"]
  node_app["Web application<br/>[app.py]"]
  node_api["Browser API client<br/>[api.js]"]
  node_web_ui["Operator panel<br/>[app.js]"]
  node_chat_ui["Chat interface<br/>[Chat.js]"]
  node_portability_ui["Portability interface<br/>[ExportWizard.js]"]
end

subgraph group_data["Persistence"]
  node_database[("Application database<br/>[engine.py]")]
  node_config_repo["Configuration repository<br/>[config_repo.py]"]
  node_contacts_repo["Contact repository<br/>[contact_repo.py]"]
  node_messages_repo["Message repository<br/>[message_repo.py]"]
  node_settings["Settings<br/>[settings.py]"]
end

subgraph group_extensions["Extensions and operations"]
  node_plugins["Plugin system<br/>[context.py]"]
  node_plugin_events["Plugin event bus<br/>[events.py]"]
  node_portability["Import and export<br/>[handlers.py]"]
  node_file_manager["Media file manager<br/>[file_manager.py]"]
  node_ai_admin["AI configuration API<br/>[ai_engine.py]"]
end

node_operator(("Operator"))
node_whatsapp_user(("WhatsApp user"))
node_whatsapp["WhatsApp"]

node_whatsapp_user -->|"sends messages"| node_whatsapp
node_whatsapp -.->|"carries messages"| node_gowa
node_gowa -->|"delivers events"| node_webhook
node_webhook -->|"uses intent runtime"| node_intents
node_webhook -->|"uses mention logic"| node_mentions
node_webhook -->|"uses contact data"| node_contacts_repo
node_webhook -->|"uses message data"| node_messages_repo
node_webhook -->|"handles media"| node_file_manager
node_webhook -->|"emits events"| node_plugin_events
node_webhook -.->|"processes replies"| node_handler
node_handler -->|"uses memory"| node_memory
node_handler -->|"runs engine"| node_ai_engine
node_handler -->|"builds agents"| node_agent_factory
node_handler -->|"emits plugin events"| node_plugin_events
node_ai_engine -->|"filters tool calls"| node_plugin_events
node_handler -.->|"sends replies"| node_gowa
node_operator -->|"uses panel"| node_web_ui
node_web_ui -->|"opens chat"| node_chat_ui
node_web_ui -.->|"requests data"| node_api
node_api -.->|"calls endpoints"| node_app
node_app -.->|"registers routes"| node_ai_admin
node_ai_admin -.->|"reads and writes"| node_config_repo
node_settings -->|"reads configuration"| node_config_repo
node_config_repo -->|"uses engine"| node_database
node_contacts_repo -->|"queries data"| node_database
node_messages_repo -->|"queries data"| node_database
node_memory -->|"reads and writes"| node_contacts_repo
node_memory -->|"reads history"| node_messages_repo
node_plugins -->|"sends WhatsApp messages"| node_gowa
node_plugins -.->|"saves assistant messages"| node_messages_repo
node_app -->|"registers plugin tools"| node_plugins
node_plugin_events -->|"builds plugin contexts"| node_plugins
node_operator -->|"manages data transfer"| node_portability_ui
node_portability -->|"imports and exports data"| node_database

click node_gowa "https://github.com/techify-one/whatsbot-lite/blob/main/gowa/client.py"
click node_webhook "https://github.com/techify-one/whatsbot-lite/blob/main/server/routes/webhook.py"
click node_handler "https://github.com/techify-one/whatsbot-lite/blob/main/agent/handler.py"
click node_ai_engine "https://github.com/techify-one/whatsbot-lite/blob/main/agent/agno_engine.py"
click node_agent_factory "https://github.com/techify-one/whatsbot-lite/blob/main/agent/agent_factory.py"
click node_intents "https://github.com/techify-one/whatsbot-lite/blob/main/agent/intent_runtime.py"
click node_mentions "https://github.com/techify-one/whatsbot-lite/blob/main/agent/group_mentions.py"
click node_memory "https://github.com/techify-one/whatsbot-lite/blob/main/agent/memory.py"
click node_app "https://github.com/techify-one/whatsbot-lite/blob/main/server/app.py"
click node_api "https://github.com/techify-one/whatsbot-lite/blob/main/web/static/js/services/api.js"
click node_web_ui "https://github.com/techify-one/whatsbot-lite/blob/main/web/static/js/app.js"
click node_chat_ui "https://github.com/techify-one/whatsbot-lite/blob/main/web/static/js/components/Chat.js"
click node_portability_ui "https://github.com/techify-one/whatsbot-lite/blob/main/web/static/js/components/portability/ExportWizard.js"
click node_database "https://github.com/techify-one/whatsbot-lite/blob/main/db/engine.py"
click node_config_repo "https://github.com/techify-one/whatsbot-lite/blob/main/db/repositories/config_repo.py"
click node_contacts_repo "https://github.com/techify-one/whatsbot-lite/blob/main/db/repositories/contact_repo.py"
click node_messages_repo "https://github.com/techify-one/whatsbot-lite/blob/main/db/repositories/message_repo.py"
click node_settings "https://github.com/techify-one/whatsbot-lite/blob/main/config/settings.py"
click node_plugins "https://github.com/techify-one/whatsbot-lite/blob/main/plugins/context.py"
click node_plugin_events "https://github.com/techify-one/whatsbot-lite/blob/main/plugins/events.py"
click node_portability "https://github.com/techify-one/whatsbot-lite/blob/main/portability/handlers.py"
click node_file_manager "https://github.com/techify-one/whatsbot-lite/blob/main/server/file_manager.py"
click node_ai_admin "https://github.com/techify-one/whatsbot-lite/blob/main/server/routes/ai_engine.py"

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_gowa,node_webhook,node_handler,node_ai_engine,node_agent_factory,node_intents,node_mentions,node_memory,node_whatsapp_user toneBlue
class node_app,node_api,node_web_ui,node_chat_ui,node_portability_ui toneAmber
class node_database,node_config_repo,node_contacts_repo,node_messages_repo,node_settings toneMint
class node_plugins,node_plugin_events,node_portability,node_file_manager,node_ai_admin toneRose
class node_operator,node_whatsapp toneIndigo
```

## Components

### Conversation automation

- [GOWA client](https://github.com/techify-one/whatsbot-lite/blob/main/gowa/client.py): `gowa/client.py`
- [Message webhook](https://github.com/techify-one/whatsbot-lite/blob/main/server/routes/webhook.py): `server/routes/webhook.py`
- [Agent handler](https://github.com/techify-one/whatsbot-lite/blob/main/agent/handler.py): `agent/handler.py`
- [AI engine](https://github.com/techify-one/whatsbot-lite/blob/main/agent/agno_engine.py): `agent/agno_engine.py`
- [Agent assembly](https://github.com/techify-one/whatsbot-lite/blob/main/agent/agent_factory.py): `agent/agent_factory.py`
- [Intent runtime](https://github.com/techify-one/whatsbot-lite/blob/main/agent/intent_runtime.py): `agent/intent_runtime.py`
- [Group mentions](https://github.com/techify-one/whatsbot-lite/blob/main/agent/group_mentions.py): `agent/group_mentions.py`
- [Contact memory](https://github.com/techify-one/whatsbot-lite/blob/main/agent/memory.py): `agent/memory.py`

### Web platform

- [Web application](https://github.com/techify-one/whatsbot-lite/blob/main/server/app.py): `server/app.py`
- [Browser API client](https://github.com/techify-one/whatsbot-lite/blob/main/web/static/js/services/api.js): `web/static/js/services/api.js`
- [Operator panel](https://github.com/techify-one/whatsbot-lite/blob/main/web/static/js/app.js): `web/static/js/app.js`
- [Chat interface](https://github.com/techify-one/whatsbot-lite/blob/main/web/static/js/components/Chat.js): `web/static/js/components/Chat.js`
- [Portability interface](https://github.com/techify-one/whatsbot-lite/blob/main/web/static/js/components/portability/ExportWizard.js): `web/static/js/components/portability/ExportWizard.js`

### Persistence

- [Application database](https://github.com/techify-one/whatsbot-lite/blob/main/db/engine.py): `db/engine.py`
- [Configuration repository](https://github.com/techify-one/whatsbot-lite/blob/main/db/repositories/config_repo.py): `db/repositories/config_repo.py`
- [Contact repository](https://github.com/techify-one/whatsbot-lite/blob/main/db/repositories/contact_repo.py): `db/repositories/contact_repo.py`
- [Message repository](https://github.com/techify-one/whatsbot-lite/blob/main/db/repositories/message_repo.py): `db/repositories/message_repo.py`
- [Settings](https://github.com/techify-one/whatsbot-lite/blob/main/config/settings.py): `config/settings.py`

### Extensions and operations

- [Plugin system](https://github.com/techify-one/whatsbot-lite/blob/main/plugins/context.py): `plugins/context.py`
- [Plugin event bus](https://github.com/techify-one/whatsbot-lite/blob/main/plugins/events.py): `plugins/events.py`
- [Import and export](https://github.com/techify-one/whatsbot-lite/blob/main/portability/handlers.py): `portability/handlers.py`
- [Media file manager](https://github.com/techify-one/whatsbot-lite/blob/main/server/file_manager.py): `server/file_manager.py`
- [AI configuration API](https://github.com/techify-one/whatsbot-lite/blob/main/server/routes/ai_engine.py): `server/routes/ai_engine.py`

### Other components

- **Operator**
- **WhatsApp user**
- **WhatsApp**

## Connections

- WhatsApp user → WhatsApp: sends messages
- WhatsApp → GOWA client: carries messages
- GOWA client → Message webhook: delivers events (evidence: `server/routes/webhook.py`)
- Message webhook → Intent runtime: uses intent runtime (evidence: `server/routes/webhook.py`)
- Message webhook → Group mentions: uses mention logic (evidence: `server/routes/webhook.py`)
- Message webhook → Contact repository: uses contact data (evidence: `server/routes/webhook.py`)
- Message webhook → Message repository: uses message data (evidence: `server/routes/webhook.py`)
- Message webhook → Media file manager: handles media (evidence: `server/routes/webhook.py`)
- Message webhook → Plugin event bus: emits events (evidence: `server/routes/webhook.py`)
- Message webhook → Agent handler: processes replies
- Agent handler → Contact memory: uses memory (evidence: `agent/handler.py`)
- Agent handler → AI engine: runs engine (evidence: `agent/handler.py`)
- Agent handler → Agent assembly: builds agents (evidence: `agent/handler.py`)
- Agent handler → Plugin event bus: emits plugin events (evidence: `agent/handler.py`)
- AI engine → Plugin event bus: filters tool calls (evidence: `agent/agno_engine.py`)
- Agent handler → GOWA client: sends replies
- Operator → Operator panel: uses panel
- Operator panel → Chat interface: opens chat (evidence: `web/static/js/app.js`)
- Operator panel → Browser API client: requests data (evidence: `web/static/js/app.js`)
- Browser API client → Web application: calls endpoints
- Web application → AI configuration API: registers routes (evidence: `server/app.py`)
- AI configuration API → Configuration repository: reads and writes
- Settings → Configuration repository: reads configuration (evidence: `config/settings.py`)
- Configuration repository → Application database: uses engine (evidence: `db/repositories/config_repo.py`)
- Contact repository → Application database: queries data (evidence: `db/repositories/contact_repo.py`)
- Message repository → Application database: queries data (evidence: `db/repositories/message_repo.py`)
- Contact memory → Contact repository: reads and writes (evidence: `agent/memory.py`)
- Contact memory → Message repository: reads history (evidence: `agent/memory.py`)
- Plugin system → GOWA client: sends WhatsApp messages (evidence: `plugins/context.py`)
- Plugin system → Message repository: saves assistant messages
- Web application → Plugin system: registers plugin tools (evidence: `server/app.py`)
- Plugin event bus → Plugin system: builds plugin contexts (evidence: `plugins/events.py`)
- Operator → Portability interface: manages data transfer
- Import and export → Application database: imports and exports data (evidence: `portability/handlers.py`)
