# vivek09-bit/wbot-python architecture

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

- Interactive diagram: https://gitdiagram.com/vivek09-bit/wbot-python
- Repository: https://github.com/vivek09-bit/wbot-python

## Overview

This is a Flask webhook bot that turns incoming WhatsApp messages into DeepSeek-backed replies. Meta verifies the webhook, then posts messages; the server validates signatures, de-duplicates and acknowledges events before processing each message on a worker thread. That flow handles commands, read receipts, bounded conversation history, model errors, and replies split and sent through Meta. The README also documents health/status endpoints and configurable credentials and runtime behavior. Source excerpts show the main calls; optional persistence is only a production suggestion, not an implemented subsystem.

Main entry points: [`app.py`](https://github.com/vivek09-bit/wbot-python/blob/main/app.py) (Flask webhook), [`bot/llm.py`](https://github.com/vivek09-bit/wbot-python/blob/main/bot/llm.py) (DeepSeek client), [`bot/whatsapp.py`](https://github.com/vivek09-bit/wbot-python/blob/main/bot/whatsapp.py) (WhatsApp client), [`bot/config.py`](https://github.com/vivek09-bit/wbot-python/blob/main/bot/config.py) (Validated settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Webhook ingress"]
  node_server["Flask webhook<br/>[app.py]"]
  node_verify["Webhook verification<br/>[app.py]"]
  node_signature["Signature validation<br/>[app.py]"]
  node_dedupe["Message de-duplication<br/>[memory.py]"]
end

subgraph group_conversation["Conversation handling"]
  node_dispatcher["Message dispatch<br/>[app.py]"]
  node_commands["Chat commands<br/>[app.py]"]
  node_history["Conversation history<br/>[memory.py]"]
end

subgraph group_integrations["External integrations"]
  node_model["DeepSeek client<br/>[llm.py]"]
  node_wa_client["WhatsApp client<br/>[whatsapp.py]"]
end

subgraph group_runtime["Runtime support"]
  node_config["Validated settings<br/>[config.py]"]
  node_health["Service and health endpoints<br/>[app.py]"]
end

node_user(("WhatsApp user"))
node_meta["Meta Cloud API"]
node_deepseek["DeepSeek API"]

node_user -->|"sends message"| node_meta
node_meta -->|"posts webhook"| node_server
node_meta -->|"verifies webhook"| node_verify
node_server -->|"validates signature"| node_signature
node_server -->|"checks message ID"| node_dedupe
node_server -->|"starts worker"| node_dispatcher
node_dispatcher -->|"handles commands"| node_commands
node_dispatcher -->|"reads and updates"| node_history
node_dispatcher -->|"requests reply"| node_model
node_model -->|"requests completion"| node_deepseek
node_dispatcher -->|"sends read and reply"| node_wa_client
node_wa_client -->|"posts messages"| node_meta
node_user -->|"receives reply"| node_meta
node_config -->|"configures runtime"| node_server
node_server -->|"serves status"| node_health

click node_server "https://github.com/vivek09-bit/wbot-python/blob/main/app.py"
click node_verify "https://github.com/vivek09-bit/wbot-python/blob/main/app.py"
click node_signature "https://github.com/vivek09-bit/wbot-python/blob/main/app.py"
click node_dedupe "https://github.com/vivek09-bit/wbot-python/blob/main/bot/memory.py"
click node_dispatcher "https://github.com/vivek09-bit/wbot-python/blob/main/app.py"
click node_commands "https://github.com/vivek09-bit/wbot-python/blob/main/app.py"
click node_history "https://github.com/vivek09-bit/wbot-python/blob/main/bot/memory.py"
click node_model "https://github.com/vivek09-bit/wbot-python/blob/main/bot/llm.py"
click node_wa_client "https://github.com/vivek09-bit/wbot-python/blob/main/bot/whatsapp.py"
click node_config "https://github.com/vivek09-bit/wbot-python/blob/main/bot/config.py"
click node_health "https://github.com/vivek09-bit/wbot-python/blob/main/app.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_server,node_verify,node_signature,node_dedupe,node_user toneBlue
class node_dispatcher,node_commands,node_history toneAmber
class node_model,node_wa_client,node_meta,node_deepseek toneMint
class node_config,node_health toneRose
```

## Components

### Webhook ingress

- [Flask webhook](https://github.com/vivek09-bit/wbot-python/blob/main/app.py): `app.py`
- [Webhook verification](https://github.com/vivek09-bit/wbot-python/blob/main/app.py): `app.py`
- [Signature validation](https://github.com/vivek09-bit/wbot-python/blob/main/app.py): `app.py`
- [Message de-duplication](https://github.com/vivek09-bit/wbot-python/blob/main/bot/memory.py): `bot/memory.py`

### Conversation handling

- [Message dispatch](https://github.com/vivek09-bit/wbot-python/blob/main/app.py): `app.py`
- [Chat commands](https://github.com/vivek09-bit/wbot-python/blob/main/app.py): `app.py`
- [Conversation history](https://github.com/vivek09-bit/wbot-python/blob/main/bot/memory.py): `bot/memory.py`

### External integrations

- [DeepSeek client](https://github.com/vivek09-bit/wbot-python/blob/main/bot/llm.py): `bot/llm.py`
- [WhatsApp client](https://github.com/vivek09-bit/wbot-python/blob/main/bot/whatsapp.py): `bot/whatsapp.py`

### Runtime support

- [Validated settings](https://github.com/vivek09-bit/wbot-python/blob/main/bot/config.py): `bot/config.py`
- [Service and health endpoints](https://github.com/vivek09-bit/wbot-python/blob/main/app.py): `app.py`

### Other components

- **WhatsApp user**
- **Meta Cloud API**
- **DeepSeek API**

## Connections

- WhatsApp user → Meta Cloud API: sends message (evidence: `README.md`)
- Meta Cloud API → Flask webhook: posts webhook (evidence: `README.md`)
- Meta Cloud API → Webhook verification: verifies webhook (evidence: `README.md`)
- Flask webhook → Signature validation: validates signature (evidence: `app.py`)
- Flask webhook → Message de-duplication: checks message ID (evidence: `app.py`)
- Flask webhook → Message dispatch: starts worker (evidence: `app.py`)
- Message dispatch → Chat commands: handles commands (evidence: `app.py`)
- Message dispatch → Conversation history: reads and updates (evidence: `app.py`)
- Message dispatch → DeepSeek client: requests reply (evidence: `app.py`)
- DeepSeek client → DeepSeek API: requests completion (evidence: `bot/llm.py`)
- Message dispatch → WhatsApp client: sends read and reply (evidence: `app.py`)
- WhatsApp client → Meta Cloud API: posts messages (evidence: `bot/whatsapp.py`)
- WhatsApp user → Meta Cloud API: receives reply (evidence: `README.md`)
- Validated settings → Flask webhook: configures runtime (evidence: `app.py`)
- Flask webhook → Service and health endpoints: serves status (evidence: `app.py`)
