# amanprojects-ops/telegram-bot-manager architecture

> Architecture diagram of the GitHub repository amanprojects-ops/telegram-bot-manager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amanprojects-ops/telegram-bot-manager
- Repository: https://github.com/amanprojects-ops/telegram-bot-manager

## Overview

Telegram Bot Manager serves Telegram users through a webhook-driven bot and provides administrators with lead and broadcast management. The main bot workflow validates and logs updates, dispatches them to message or callback handling, then supports service and project discovery, brochure delivery, and quote capture. Admins review and update leads or create and launch broadcasts; scheduled and queued jobs deliver messages to bot users. The README documents campaign deep links, cached brochure file IDs, and webhook protections, but those implementation details were not fully sampled, so their internal wiring is not expanded here.

Main entry points: [`app/Services/Telegram/GeneralFlowService.php`](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Services/Telegram/GeneralFlowService.php) (Menus and catalog), [`app/Services/Telegram/CallbackHandler.php`](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Services/Telegram/CallbackHandler.php) (Callback handling), [`app/Jobs/ProcessBroadcast.php`](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Jobs/ProcessBroadcast.php) (Broadcast processor), [`app/Services/Telegram/TelegramApi.php`](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Services/Telegram/TelegramApi.php) (Telegram API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bot["Telegram Bot"]
  node_webhook["Webhook endpoint"]
  node_bot_router["Bot update router<br/>[TelegramBot.php]"]
  node_message_handler["Message handling<br/>[MessageHandler.php]"]
  node_callback_handler["Callback handling"]
  node_telegram_api["Telegram API client<br/>[TelegramApi.php]"]
  node_telegram_users["Bot user records<br/>[TelegramUser.php]"]
end

subgraph group_domain["Business Features"]
  node_general_flow["Menus and catalog"]
  node_service_catalog["Services catalog<br/>[Service.php]"]
  node_pricing_plan["Pricing plans<br/>[PricingPlan.php]"]
  node_project_catalog["Projects catalog<br/>[Project.php]"]
  node_brochure_service["Brochure delivery"]
  node_brochure_records["Brochure records<br/>[Brochure.php]"]
  node_lead_service["Quote and leads<br/>[LeadService.php]"]
  node_lead_records["Lead records<br/>[TelegramLead.php]"]
end

subgraph group_admin["Admin Operations"]
  node_lead_controller["Lead administration<br/>[LeadController.php]"]
  node_broadcast_controller["Broadcast management"]
  node_dashboard_controller["Admin dashboard"]
end

subgraph group_delivery["Broadcast Delivery"]
  node_broadcast_records["Broadcast records<br/>[Broadcast.php]"]
  node_broadcast_scheduler["Scheduled dispatch"]
  node_process_broadcast["Broadcast processor"]
  node_send_message_job["Send message job"]
end

node_telegram_user(("Telegram user"))
node_telegram_platform(("Telegram platform"))
node_admin_user(("Administrator"))
node_database[("Application database")]
node_queue_worker(("Queue worker"))

node_telegram_user -->|"sends updates"| node_webhook
node_webhook -->|"checks and logs updates"| node_database
node_webhook -->|"dispatches update"| node_bot_router
node_bot_router -->|"routes messages"| node_message_handler
node_bot_router -->|"routes callbacks"| node_callback_handler
node_message_handler -->|"handles quote input"| node_lead_service
node_message_handler -->|"handles bot flow"| node_general_flow
node_callback_handler -->|"dispatches quote actions"| node_lead_service
node_callback_handler -->|"dispatches brochure actions"| node_brochure_service
node_callback_handler -->|"dispatches menu actions"| node_general_flow
node_callback_handler -->|"reads services"| node_service_catalog
node_general_flow -->|"reads services"| node_service_catalog
node_general_flow -->|"reads pricing"| node_pricing_plan
node_general_flow -->|"reads projects"| node_project_catalog
node_brochure_service -->|"uses brochure data"| node_brochure_records
node_brochure_service -->|"sends brochure"| node_telegram_api
node_lead_service -->|"creates and updates leads"| node_lead_records
node_lead_service -->|"persists lead state"| node_database
node_message_handler -->|"sends replies"| node_telegram_api
node_general_flow -->|"sends menus"| node_telegram_api
node_telegram_api -->|"calls Bot API"| node_telegram_platform
node_telegram_user -->|"uses bot"| node_telegram_platform
node_admin_user -->|"manages leads"| node_lead_controller
node_admin_user -->|"manages broadcasts"| node_broadcast_controller
node_admin_user -->|"views dashboard"| node_dashboard_controller
node_lead_controller -->|"reads and updates"| node_lead_records
node_broadcast_controller -->|"creates and reads"| node_broadcast_records
node_broadcast_controller -->|"counts recipients"| node_telegram_users
node_broadcast_controller -->|"dispatches job"| node_process_broadcast
node_broadcast_scheduler -->|"finds due broadcasts"| node_broadcast_records
node_broadcast_scheduler -->|"dispatches job"| node_process_broadcast
node_queue_worker -->|"runs job"| node_process_broadcast
node_process_broadcast -->|"updates progress"| node_broadcast_records
node_process_broadcast -->|"dispatches recipient jobs"| node_send_message_job
node_send_message_job -->|"loads recipient"| node_telegram_users
node_send_message_job -->|"sends broadcast"| node_telegram_api
node_broadcast_records -->|"persists broadcasts"| node_database
node_telegram_users -->|"persists bot users"| node_database
node_lead_records -->|"persists leads"| node_database

click node_webhook "https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Http/Controllers/Telegram/WebhookController.php"
click node_bot_router "https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Services/Telegram/TelegramBot.php"
click node_message_handler "https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Services/Telegram/MessageHandler.php"
click node_callback_handler "https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Services/Telegram/CallbackHandler.php"
click node_general_flow "https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Services/Telegram/GeneralFlowService.php"
click node_service_catalog "https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Models/Service.php"
click node_pricing_plan "https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Models/PricingPlan.php"
click node_project_catalog "https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Models/Project.php"
click node_brochure_service "https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Services/Telegram/BrochureService.php"
click node_brochure_records "https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Models/Brochure.php"
click node_lead_service "https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Services/Telegram/LeadService.php"
click node_lead_records "https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Models/TelegramLead.php"
click node_telegram_api "https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Services/Telegram/TelegramApi.php"
click node_lead_controller "https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Http/Controllers/Admin/LeadController.php"
click node_broadcast_controller "https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Http/Controllers/Admin/BroadcastController.php"
click node_dashboard_controller "https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Http/Controllers/Admin/DashboardController.php"
click node_broadcast_records "https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Models/Broadcast.php"
click node_broadcast_scheduler "https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Console/Commands/DispatchScheduledBroadcasts.php"
click node_process_broadcast "https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Jobs/ProcessBroadcast.php"
click node_send_message_job "https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Jobs/SendBroadcastMessage.php"
click node_telegram_users "https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Models/TelegramUser.php"

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_webhook,node_bot_router,node_message_handler,node_callback_handler,node_telegram_api,node_telegram_users,node_telegram_user toneBlue
class node_general_flow,node_service_catalog,node_pricing_plan,node_project_catalog,node_brochure_service,node_brochure_records,node_lead_service,node_lead_records,node_database toneAmber
class node_lead_controller,node_broadcast_controller,node_dashboard_controller toneMint
class node_broadcast_records,node_broadcast_scheduler,node_process_broadcast,node_send_message_job,node_queue_worker toneRose
class node_telegram_platform,node_admin_user toneIndigo
```

## Components

### Telegram Bot

- [Webhook endpoint](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Http/Controllers/Telegram/WebhookController.php): `app/Http/Controllers/Telegram/WebhookController.php`
- [Bot update router](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Services/Telegram/TelegramBot.php): `app/Services/Telegram/TelegramBot.php`
- [Message handling](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Services/Telegram/MessageHandler.php): `app/Services/Telegram/MessageHandler.php`
- [Callback handling](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Services/Telegram/CallbackHandler.php): `app/Services/Telegram/CallbackHandler.php`
- [Telegram API client](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Services/Telegram/TelegramApi.php): `app/Services/Telegram/TelegramApi.php`
- [Bot user records](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Models/TelegramUser.php): `app/Models/TelegramUser.php`

### Business Features

- [Menus and catalog](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Services/Telegram/GeneralFlowService.php): `app/Services/Telegram/GeneralFlowService.php`
- [Services catalog](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Models/Service.php): `app/Models/Service.php`
- [Pricing plans](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Models/PricingPlan.php): `app/Models/PricingPlan.php`
- [Projects catalog](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Models/Project.php): `app/Models/Project.php`
- [Brochure delivery](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Services/Telegram/BrochureService.php): `app/Services/Telegram/BrochureService.php`
- [Brochure records](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Models/Brochure.php): `app/Models/Brochure.php`
- [Quote and leads](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Services/Telegram/LeadService.php): `app/Services/Telegram/LeadService.php`
- [Lead records](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Models/TelegramLead.php): `app/Models/TelegramLead.php`

### Admin Operations

- [Lead administration](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Http/Controllers/Admin/LeadController.php): `app/Http/Controllers/Admin/LeadController.php`
- [Broadcast management](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Http/Controllers/Admin/BroadcastController.php): `app/Http/Controllers/Admin/BroadcastController.php`
- [Admin dashboard](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Http/Controllers/Admin/DashboardController.php): `app/Http/Controllers/Admin/DashboardController.php`

### Broadcast Delivery

- [Broadcast records](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Models/Broadcast.php): `app/Models/Broadcast.php`
- [Scheduled dispatch](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Console/Commands/DispatchScheduledBroadcasts.php): `app/Console/Commands/DispatchScheduledBroadcasts.php`
- [Broadcast processor](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Jobs/ProcessBroadcast.php): `app/Jobs/ProcessBroadcast.php`
- [Send message job](https://github.com/amanprojects-ops/telegram-bot-manager/blob/master/app/Jobs/SendBroadcastMessage.php): `app/Jobs/SendBroadcastMessage.php`

### Other components

- **Telegram user**
- **Telegram platform**
- **Administrator**
- **Application database**
- **Queue worker**

## Connections

- Telegram user → Webhook endpoint: sends updates
- Webhook endpoint → Application database: checks and logs updates
- Webhook endpoint → Bot update router: dispatches update
- Bot update router → Message handling: routes messages
- Bot update router → Callback handling: routes callbacks
- Message handling → Quote and leads: handles quote input
- Message handling → Menus and catalog: handles bot flow
- Callback handling → Quote and leads: dispatches quote actions
- Callback handling → Brochure delivery: dispatches brochure actions
- Callback handling → Menus and catalog: dispatches menu actions
- Callback handling → Services catalog: reads services
- Menus and catalog → Services catalog: reads services
- Menus and catalog → Pricing plans: reads pricing
- Menus and catalog → Projects catalog: reads projects
- Brochure delivery → Brochure records: uses brochure data
- Brochure delivery → Telegram API client: sends brochure
- Quote and leads → Lead records: creates and updates leads
- Quote and leads → Application database: persists lead state
- Message handling → Telegram API client: sends replies
- Menus and catalog → Telegram API client: sends menus
- Telegram API client → Telegram platform: calls Bot API
- Telegram user → Telegram platform: uses bot
- Administrator → Lead administration: manages leads
- Administrator → Broadcast management: manages broadcasts
- Administrator → Admin dashboard: views dashboard
- Lead administration → Lead records: reads and updates
- Broadcast management → Broadcast records: creates and reads
- Broadcast management → Bot user records: counts recipients
- Broadcast management → Broadcast processor: dispatches job
- Scheduled dispatch → Broadcast records: finds due broadcasts
- Scheduled dispatch → Broadcast processor: dispatches job
- Queue worker → Broadcast processor: runs job
- Broadcast processor → Broadcast records: updates progress
- Broadcast processor → Send message job: dispatches recipient jobs
- Send message job → Bot user records: loads recipient
- Send message job → Telegram API client: sends broadcast
- Broadcast records → Application database: persists broadcasts
- Bot user records → Application database: persists bot users
- Lead records → Application database: persists leads