# edyoda/aichatbot architecture

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

- Interactive diagram: https://gitdiagram.com/edyoda/aichatbot
- Repository: https://github.com/edyoda/aichatbot

## Overview

EdYoda ChatBotAgent answers learning-advisor questions through WhatsApp, browser chat, or terminal clients. The main flow is an inbound message to the shared chatbot, which routes and retrieves course or FAQ context, generates and validates a Claude response, then returns it through the originating channel. Redis holds session history; the WATI application also logs exchanges and manages deflections and images. Optional branches cover LMS batch-date tools, customer-name capture, and CRM lead qualification and note creation. Unsampled branches are included where the README documents them; uncertain internal calls are omitted.

Main entry points: [`app/edyoda_chatbot.py`](https://github.com/edyoda/aichatbot/blob/main/app/edyoda_chatbot.py) (Chatbot engine), [`app/main.py`](https://github.com/edyoda/aichatbot/blob/main/app/main.py) (WATI webhook app), [`app/crm_notes/service.py`](https://github.com/edyoda/aichatbot/blob/main/app/crm_notes/service.py) (CRM note service), [`app/crm_notes/orchestrator.py`](https://github.com/edyoda/aichatbot/blob/main/app/crm_notes/orchestrator.py) (Lead and note orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_channels["Chat channels"]
  node_wati_app["WATI webhook app<br/>[main.py]"]
  node_web_app["Web chat API<br/>[web_chat.py]"]
  node_web_ui["Browser chat UI<br/>[chat.html]"]
  node_terminal_chat["Terminal chat<br/>[local_chat.py]"]
end

subgraph group_answering["Answer generation"]
  node_chatbot["Chatbot engine<br/>[edyoda_chatbot.py]"]
  node_rag_retrieval["RAG retrieval<br/>[edyoda_chatbot.py]"]
  node_claude_answer["Claude responder<br/>[edyoda_chatbot.py]"]
  node_reply_validator["Reply validator<br/>[edyoda_chatbot.py]"]
  node_prompt_files["Hot-reloaded prompts<br/>[system_prompt.txt]"]
  node_mcp_client["MCP client bridge<br/>[mcp_client.py]"]
end

subgraph group_state["Session and logging"]
  node_redis_history[("Redis session history<br/>[chat_history.py]")]
  node_sqlite_logs[("SQLite conversation log<br/>[db.py]")]
end

subgraph group_crm["CRM operations"]
  node_name_capture["Customer-name capture<br/>[name_capture.py]"]
  node_crm_batch["CRM note service<br/>[service.py]"]
  node_conversation_source["Conversation sourcing<br/>[source.py]"]
  node_lead_qualification["Lead qualification<br/>[qualify.py]"]
  node_crm_orchestrator["Lead and note orchestration<br/>[orchestrator.py]"]
  node_lead_dedup["Lead deduplication<br/>[dedup.py]"]
  node_call_summary["Call-prep summarizer<br/>[summarize.py]"]
  node_crm_provider["CRM provider interface<br/>[base.py]"]
  node_zoho_provider["Zoho CRM provider<br/>[zoho.py]"]
end

subgraph group_integrations["External services"]
  node_pinecone[("Pinecone indexes")]
  node_claude_service["Claude API"]
  node_lms_tools["LMS batch-date tool"]
  node_lms_service["EdYoda LMS"]
  node_zoho_crm["Zoho CRM"]
  node_openrouter["OpenRouter API"]
end

node_whatsapp_user(("WhatsApp user"))
node_web_user(("Web chat user"))
node_terminal_user(("Terminal user"))

node_whatsapp_user -->|"sends message"| node_wati_app
node_web_user -->|"sends message"| node_web_ui
node_web_ui -->|"calls chat API"| node_web_app
node_web_app -->|"calls ask"| node_chatbot
node_terminal_user -->|"enters message"| node_terminal_chat
node_terminal_chat -->|"uses core"| node_chatbot
node_wati_app -->|"uses core"| node_chatbot
node_chatbot -->|"routes and retrieves"| node_rag_retrieval
node_rag_retrieval -->|"searches indexes"| node_pinecone
node_chatbot -->|"generates reply"| node_claude_answer
node_claude_answer -->|"requests completion"| node_claude_service
node_chatbot -->|"validates reply"| node_reply_validator
node_reply_validator -->|"checks and rewrites"| node_claude_service
node_chatbot -->|"loads prompts"| node_prompt_files
node_chatbot -->|"reads and writes"| node_redis_history
node_wati_app -->|"logs exchanges"| node_sqlite_logs
node_chatbot -->|"uses tool bridge"| node_mcp_client
node_mcp_client -->|"invokes tools"| node_lms_tools
node_lms_tools -->|"looks up batches"| node_lms_service
node_wati_app -->|"handles names"| node_name_capture
node_name_capture -->|"reads and updates metadata"| node_redis_history
node_name_capture -->|"looks up and updates leads"| node_crm_provider
node_wati_app -->|"triggers CRM work"| node_crm_batch
node_crm_batch -->|"loads conversations"| node_conversation_source
node_crm_batch -->|"qualifies conversations"| node_lead_qualification
node_crm_batch -->|"processes qualified leads"| node_crm_orchestrator
node_crm_batch -->|"reads and marks state"| node_redis_history
node_crm_orchestrator -.->|"deduplicates leads"| node_lead_dedup
node_crm_orchestrator -.->|"creates call summary"| node_call_summary
node_crm_orchestrator -.->|"uses provider"| node_crm_provider
node_crm_provider -->|"selects provider"| node_zoho_provider
node_zoho_provider -->|"calls CRM API"| node_zoho_crm
node_call_summary -->|"summarizes transcript"| node_openrouter

click node_wati_app "https://github.com/edyoda/aichatbot/blob/main/app/main.py"
click node_web_app "https://github.com/edyoda/aichatbot/blob/main/web_chat.py"
click node_web_ui "https://github.com/edyoda/aichatbot/blob/main/static/chat.html"
click node_terminal_chat "https://github.com/edyoda/aichatbot/blob/main/local_chat.py"
click node_chatbot "https://github.com/edyoda/aichatbot/blob/main/app/edyoda_chatbot.py"
click node_rag_retrieval "https://github.com/edyoda/aichatbot/blob/main/app/edyoda_chatbot.py"
click node_claude_answer "https://github.com/edyoda/aichatbot/blob/main/app/edyoda_chatbot.py"
click node_reply_validator "https://github.com/edyoda/aichatbot/blob/main/app/edyoda_chatbot.py"
click node_prompt_files "https://github.com/edyoda/aichatbot/blob/main/app/system_prompt.txt"
click node_mcp_client "https://github.com/edyoda/aichatbot/blob/main/app/mcp_client.py"
click node_lms_tools "https://github.com/edyoda/aichatbot/blob/main/mcp_servers/edyoda_lms_server.py"
click node_redis_history "https://github.com/edyoda/aichatbot/blob/main/app/chat_history.py"
click node_sqlite_logs "https://github.com/edyoda/aichatbot/blob/main/app/db.py"
click node_name_capture "https://github.com/edyoda/aichatbot/blob/main/app/name_capture.py"
click node_crm_batch "https://github.com/edyoda/aichatbot/blob/main/app/crm_notes/service.py"
click node_conversation_source "https://github.com/edyoda/aichatbot/blob/main/app/crm_notes/source.py"
click node_lead_qualification "https://github.com/edyoda/aichatbot/blob/main/app/crm_notes/qualify.py"
click node_crm_orchestrator "https://github.com/edyoda/aichatbot/blob/main/app/crm_notes/orchestrator.py"
click node_lead_dedup "https://github.com/edyoda/aichatbot/blob/main/app/crm_notes/dedup.py"
click node_call_summary "https://github.com/edyoda/aichatbot/blob/main/app/crm_notes/summarize.py"
click node_crm_provider "https://github.com/edyoda/aichatbot/blob/main/app/crm_notes/crm/base.py"
click node_zoho_provider "https://github.com/edyoda/aichatbot/blob/main/app/crm_notes/crm/zoho.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_wati_app,node_web_app,node_web_ui,node_terminal_chat,node_whatsapp_user,node_web_user,node_terminal_user toneBlue
class node_chatbot,node_rag_retrieval,node_claude_answer,node_reply_validator,node_prompt_files,node_mcp_client toneAmber
class node_redis_history,node_sqlite_logs toneMint
class node_name_capture,node_crm_batch,node_conversation_source,node_lead_qualification,node_crm_orchestrator,node_lead_dedup,node_call_summary,node_crm_provider,node_zoho_provider toneRose
class node_pinecone,node_claude_service,node_lms_tools,node_lms_service,node_zoho_crm,node_openrouter toneIndigo
```

## Components

### Chat channels

- [WATI webhook app](https://github.com/edyoda/aichatbot/blob/main/app/main.py): `app/main.py`
- [Web chat API](https://github.com/edyoda/aichatbot/blob/main/web_chat.py): `web_chat.py`
- [Browser chat UI](https://github.com/edyoda/aichatbot/blob/main/static/chat.html): `static/chat.html`
- [Terminal chat](https://github.com/edyoda/aichatbot/blob/main/local_chat.py): `local_chat.py`

### Answer generation

- [Chatbot engine](https://github.com/edyoda/aichatbot/blob/main/app/edyoda_chatbot.py): `app/edyoda_chatbot.py`
- [RAG retrieval](https://github.com/edyoda/aichatbot/blob/main/app/edyoda_chatbot.py): `app/edyoda_chatbot.py`
- [Claude responder](https://github.com/edyoda/aichatbot/blob/main/app/edyoda_chatbot.py): `app/edyoda_chatbot.py`
- [Reply validator](https://github.com/edyoda/aichatbot/blob/main/app/edyoda_chatbot.py): `app/edyoda_chatbot.py`
- [Hot-reloaded prompts](https://github.com/edyoda/aichatbot/blob/main/app/system_prompt.txt): `app/system_prompt.txt`
- [MCP client bridge](https://github.com/edyoda/aichatbot/blob/main/app/mcp_client.py): `app/mcp_client.py`

### Session and logging

- [Redis session history](https://github.com/edyoda/aichatbot/blob/main/app/chat_history.py): `app/chat_history.py`
- [SQLite conversation log](https://github.com/edyoda/aichatbot/blob/main/app/db.py): `app/db.py`

### CRM operations

- [Customer-name capture](https://github.com/edyoda/aichatbot/blob/main/app/name_capture.py): `app/name_capture.py`
- [CRM note service](https://github.com/edyoda/aichatbot/blob/main/app/crm_notes/service.py): `app/crm_notes/service.py`
- [Conversation sourcing](https://github.com/edyoda/aichatbot/blob/main/app/crm_notes/source.py): `app/crm_notes/source.py`
- [Lead qualification](https://github.com/edyoda/aichatbot/blob/main/app/crm_notes/qualify.py): `app/crm_notes/qualify.py`
- [Lead and note orchestration](https://github.com/edyoda/aichatbot/blob/main/app/crm_notes/orchestrator.py): `app/crm_notes/orchestrator.py`
- [Lead deduplication](https://github.com/edyoda/aichatbot/blob/main/app/crm_notes/dedup.py): `app/crm_notes/dedup.py`
- [Call-prep summarizer](https://github.com/edyoda/aichatbot/blob/main/app/crm_notes/summarize.py): `app/crm_notes/summarize.py`
- [CRM provider interface](https://github.com/edyoda/aichatbot/blob/main/app/crm_notes/crm/base.py): `app/crm_notes/crm/base.py`
- [Zoho CRM provider](https://github.com/edyoda/aichatbot/blob/main/app/crm_notes/crm/zoho.py): `app/crm_notes/crm/zoho.py`

### External services

- **Pinecone indexes**
- **Claude API**
- [LMS batch-date tool](https://github.com/edyoda/aichatbot/blob/main/mcp_servers/edyoda_lms_server.py): `mcp_servers/edyoda_lms_server.py`
- **EdYoda LMS**
- **Zoho CRM**
- **OpenRouter API**

### Other components

- **WhatsApp user**
- **Web chat user**
- **Terminal user**

## Connections

- WhatsApp user → WATI webhook app: sends message (evidence: `README.md`)
- Web chat user → Browser chat UI: sends message (evidence: `README.md`)
- Browser chat UI → Web chat API: calls chat API (evidence: `README.md`)
- Web chat API → Chatbot engine: calls ask (evidence: `web_chat.py`)
- Terminal user → Terminal chat: enters message (evidence: `README.md`)
- Terminal chat → Chatbot engine: uses core (evidence: `README.md`)
- WATI webhook app → Chatbot engine: uses core (evidence: `README.md`)
- Chatbot engine → RAG retrieval: routes and retrieves (evidence: `README.md`)
- RAG retrieval → Pinecone indexes: searches indexes (evidence: `README.md`)
- Chatbot engine → Claude responder: generates reply (evidence: `README.md`)
- Claude responder → Claude API: requests completion (evidence: `README.md`)
- Chatbot engine → Reply validator: validates reply (evidence: `README.md`)
- Reply validator → Claude API: checks and rewrites (evidence: `README.md`)
- Chatbot engine → Hot-reloaded prompts: loads prompts (evidence: `README.md`)
- Chatbot engine → Redis session history: reads and writes (evidence: `app/edyoda_chatbot.py`)
- WATI webhook app → SQLite conversation log: logs exchanges (evidence: `app/main.py`)
- Chatbot engine → MCP client bridge: uses tool bridge (evidence: `app/edyoda_chatbot.py`)
- MCP client bridge → LMS batch-date tool: invokes tools (evidence: `README.md`)
- LMS batch-date tool → EdYoda LMS: looks up batches (evidence: `mcp_servers/edyoda_lms_server.py`)
- WATI webhook app → Customer-name capture: handles names (evidence: `app/main.py`)
- Customer-name capture → Redis session history: reads and updates metadata (evidence: `app/name_capture.py`)
- Customer-name capture → CRM provider interface: looks up and updates leads (evidence: `app/name_capture.py`)
- WATI webhook app → CRM note service: triggers CRM work (evidence: `app/main.py`)
- CRM note service → Conversation sourcing: loads conversations (evidence: `app/crm_notes/service.py`)
- CRM note service → Lead qualification: qualifies conversations (evidence: `app/crm_notes/service.py`)
- CRM note service → Lead and note orchestration: processes qualified leads (evidence: `app/crm_notes/service.py`)
- CRM note service → Redis session history: reads and marks state (evidence: `app/crm_notes/service.py`)
- Lead and note orchestration → Lead deduplication: deduplicates leads
- Lead and note orchestration → Call-prep summarizer: creates call summary
- Lead and note orchestration → CRM provider interface: uses provider
- CRM provider interface → Zoho CRM provider: selects provider (evidence: `app/crm_notes/crm/base.py`)
- Zoho CRM provider → Zoho CRM: calls CRM API (evidence: `app/crm_notes/crm/zoho.py`)
- Call-prep summarizer → OpenRouter API: summarizes transcript (evidence: `app/crm_notes/summarize.py`)