# bora168-coder-kh/telegram-ai-chatbot-management-system architecture

> Architecture diagram of the GitHub repository bora168-coder-kh/telegram-ai-chatbot-management-system, 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/bora168-coder-kh/telegram-ai-chatbot-management-system
- Repository: https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system

## Overview

Telegram users send messages through the bot; handlers register users, enforce access rules, dispatch commands or route questions, then save and send replies. The router checks rules, FAQ, knowledge articles, AI, and fallback in order. Users can request human support and rate answers. Administrators use the dashboard to review users, FAQs, unknown questions, and statistics. The README documents broader capabilities than the sampled implementation; unsampled or planned features are represented only where supported by the tree or documentation, and evidence limits are reflected in the edges.

Main entry points: [`app/bot/handlers.py`](https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/bot/handlers.py) (Bot handlers), [`app/models.py`](https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/models.py) (Domain models), [`app/db.py`](https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/db.py) (Database access), [`app/web/main.py`](https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/web/main.py) (Admin dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telegram["Telegram bot"]
  node_bot_runtime["Bot runtime<br/>[main.py]"]
  node_handlers["Bot handlers<br/>[handlers.py]"]
  node_keyboards["Keyboards<br/>[keyboards.py]"]
  node_localization["Localization<br/>[i18n.py]"]
end

subgraph group_answering["Answering services"]
  node_user_conversations["User conversations<br/>[users.py]"]
  node_response_router["Response router<br/>[router.py]"]
  node_keyword_rules["Keyword rules<br/>[rules.py]"]
  node_ai_service["AI service<br/>[ai.py]"]
  node_human_handoff["Human handoff<br/>[users.py]"]
end

subgraph group_admin["Admin dashboard"]
  node_admin_dashboard["Admin dashboard<br/>[main.py]"]
  node_dashboard_stats["Dashboard statistics<br/>[stats.py]"]
end

subgraph group_data["Data and configuration"]
  node_seed_data["Default data<br/>[seed.py]"]
  node_settings["Application settings<br/>[config.py]"]
  node_database_access["Database access<br/>[db.py]"]
  node_domain_models["Domain models<br/>[models.py]"]
  node_database[("SQL database")]
end

node_telegram_user(("Telegram user"))
node_telegram_api["Telegram API"]

node_telegram_user -->|"sends messages"| node_telegram_api
node_telegram_api -->|"delivers updates"| node_bot_runtime
node_bot_runtime -->|"registers router"| node_handlers
node_bot_runtime -->|"initializes database"| node_database_access
node_bot_runtime -->|"seeds defaults"| node_seed_data
node_handlers -->|"sends replies"| node_telegram_api
node_handlers -->|"manages sessions"| node_user_conversations
node_handlers -->|"routes questions"| node_response_router
node_handlers -->|"builds keyboards"| node_keyboards
node_keyboards -->|"gets button text"| node_localization
node_handlers -->|"gets response text"| node_localization
node_handlers -->|"requests support"| node_human_handoff
node_response_router -->|"checks rules"| node_keyword_rules
node_response_router -->|"requests generation"| node_ai_service
node_response_router -->|"queries FAQ and articles"| node_domain_models
node_handlers -->|"records feedback"| node_domain_models
node_admin_dashboard -->|"loads KPIs"| node_dashboard_stats
node_admin_dashboard -->|"reads and updates records"| node_domain_models
node_admin_dashboard -->|"opens sessions"| node_database_access
node_admin_dashboard -->|"seeds defaults"| node_seed_data
node_dashboard_stats -->|"counts activity"| node_domain_models
node_user_conversations -->|"persists conversations"| node_domain_models
node_human_handoff -->|"marks support open"| node_domain_models
node_database_access -->|"reads database URL"| node_settings
node_database_access -->|"creates schema"| node_domain_models
node_database_access -->|"connects to"| node_database
node_seed_data -->|"adds defaults"| node_domain_models
node_ai_service -->|"reads AI settings"| node_settings

click node_bot_runtime "https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/bot/main.py"
click node_handlers "https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/bot/handlers.py"
click node_keyboards "https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/bot/keyboards.py"
click node_localization "https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/i18n.py"
click node_user_conversations "https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/services/users.py"
click node_response_router "https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/services/router.py"
click node_keyword_rules "https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/services/rules.py"
click node_ai_service "https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/services/ai.py"
click node_human_handoff "https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/services/users.py"
click node_admin_dashboard "https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/web/main.py"
click node_dashboard_stats "https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/services/stats.py"
click node_seed_data "https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/seed.py"
click node_settings "https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/config.py"
click node_database_access "https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/db.py"
click node_domain_models "https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/models.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_bot_runtime,node_handlers,node_keyboards,node_localization,node_telegram_user toneBlue
class node_user_conversations,node_response_router,node_keyword_rules,node_ai_service,node_human_handoff toneAmber
class node_admin_dashboard,node_dashboard_stats,node_telegram_api toneMint
class node_seed_data,node_settings,node_database_access,node_domain_models,node_database toneRose
```

## Components

### Telegram bot

- [Bot runtime](https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/bot/main.py): `app/bot/main.py`
- [Bot handlers](https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/bot/handlers.py): `app/bot/handlers.py`
- [Keyboards](https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/bot/keyboards.py): `app/bot/keyboards.py`
- [Localization](https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/i18n.py): `app/i18n.py`

### Answering services

- [User conversations](https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/services/users.py): `app/services/users.py`
- [Response router](https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/services/router.py): `app/services/router.py`
- [Keyword rules](https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/services/rules.py): `app/services/rules.py`
- [AI service](https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/services/ai.py): `app/services/ai.py`
- [Human handoff](https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/services/users.py): `app/services/users.py`

### Admin dashboard

- [Admin dashboard](https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/web/main.py): `app/web/main.py`
- [Dashboard statistics](https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/services/stats.py): `app/services/stats.py`

### Data and configuration

- [Default data](https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/seed.py): `app/seed.py`
- [Application settings](https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/config.py): `app/config.py`
- [Database access](https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/db.py): `app/db.py`
- [Domain models](https://github.com/bora168-coder-kh/telegram-ai-chatbot-management-system/blob/main/app/models.py): `app/models.py`
- **SQL database**

### Other components

- **Telegram user**
- **Telegram API**

## Connections

- Telegram user → Telegram API: sends messages (evidence: `README.md`)
- Telegram API → Bot runtime: delivers updates (evidence: `README.md`)
- Bot runtime → Bot handlers: registers router (evidence: `app/bot/main.py`)
- Bot runtime → Database access: initializes database (evidence: `app/bot/main.py`)
- Bot runtime → Default data: seeds defaults (evidence: `app/bot/main.py`)
- Bot handlers → Telegram API: sends replies (evidence: `README.md`)
- Bot handlers → User conversations: manages sessions (evidence: `app/bot/handlers.py`)
- Bot handlers → Response router: routes questions (evidence: `app/bot/handlers.py`)
- Bot handlers → Keyboards: builds keyboards (evidence: `app/bot/handlers.py`)
- Keyboards → Localization: gets button text (evidence: `app/bot/keyboards.py`)
- Bot handlers → Localization: gets response text (evidence: `app/bot/handlers.py`)
- Bot handlers → Human handoff: requests support (evidence: `README.md`)
- Response router → Keyword rules: checks rules (evidence: `app/services/router.py`)
- Response router → AI service: requests generation (evidence: `app/services/router.py`)
- Response router → Domain models: queries FAQ and articles (evidence: `app/services/router.py`)
- Bot handlers → Domain models: records feedback (evidence: `app/bot/handlers.py`)
- Admin dashboard → Dashboard statistics: loads KPIs (evidence: `app/web/main.py`)
- Admin dashboard → Domain models: reads and updates records (evidence: `app/web/main.py`)
- Admin dashboard → Database access: opens sessions (evidence: `app/web/main.py`)
- Admin dashboard → Default data: seeds defaults (evidence: `app/web/main.py`)
- Dashboard statistics → Domain models: counts activity (evidence: `app/services/stats.py`)
- User conversations → Domain models: persists conversations (evidence: `app/services/users.py`)
- Human handoff → Domain models: marks support open (evidence: `README.md`)
- Database access → Application settings: reads database URL (evidence: `app/db.py`)
- Database access → Domain models: creates schema (evidence: `app/db.py`)
- Database access → SQL database: connects to (evidence: `app/db.py`)
- Default data → Domain models: adds defaults (evidence: `app/seed.py`)
- AI service → Application settings: reads AI settings (evidence: `app/services/ai.py`)
