# prog-time/tg-support-bot architecture

> Architecture diagram of the GitHub repository prog-time/tg-support-bot, 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/prog-time/tg-support-bot
- Repository: https://github.com/prog-time/tg-support-bot

## Overview

TG Support Bot is a multichannel customer-support platform: Telegram, VK, Max, Avito, email, website widgets, and external APIs feed conversations that operators handle in an admin workspace or Telegram group topics. The main workflow stores messages and routes operator replies back through the originating channel; AI-assisted replies are an additional branch. The graph reflects README-documented capabilities and relationships visible in the supplied excerpts and SOURCE INDEX; unsampled channel internals are represented at their controller or service paths without asserting unverified calls.

Main entry points: [`app/Modules/Telegram/Controllers/TelegramBotController.php`](https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Telegram/Controllers/TelegramBotController.php) (Telegram updates), [`app/Models/Message.php`](https://github.com/prog-time/tg-support-bot/blob/main/app/Models/Message.php) (Message history), [`app/Modules/External/Controllers/WidgetController.php`](https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/External/Controllers/WidgetController.php) (Website widget API), [`app/Modules/Telegram/Services/Tg/TgMessageService.php`](https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Telegram/Services/Tg/TgMessageService.php) (Telegram group topics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Channels and intake"]
  node_telegram_ingress["Telegram updates"]
  node_vk_ingress["VK updates"]
  node_max_ingress["Max updates"]
  node_avito_ingress["Avito updates"]
  node_email_ingress["Email inbox"]
  node_widget_api["Website widget API"]
  node_external_api["External traffic API"]
end

subgraph group_conversation["Conversation handling"]
  node_conversation_users[("Support conversations<br/>[BotUser.php]")]
  node_message_history[("Message history<br/>[Message.php]")]
  node_telegram_topics["Telegram group topics"]
end

subgraph group_operator["Operator workspace"]
  node_admin_workspace["Manager chat workspace"]
  node_ai_assistant["AI assistant"]
  node_ai_delivery["AI answer delivery"]
end

subgraph group_platform["Platform services"]
  node_channel_delivery["Channel messaging"]
  node_settings[("Channel settings")]
  node_external_source_registry[("External source registry<br/>[ExternalSource.php]")]
  node_avito_service["Avito messaging"]
  node_email_service["Email messaging"]
  node_vk_service["VK messaging"]
  node_max_service["Max messaging"]
end

node_telegram_users(("Telegram users"))
node_vk_users(("VK users"))
node_max_users(("Max users"))
node_avito_users(("Avito users"))
node_email_users(("Email users"))
node_website_users(("Website users"))
node_external_sources(("External API sources"))

node_telegram_users -->|"send updates"| node_telegram_ingress
node_vk_users -->|"send updates"| node_vk_ingress
node_max_users -->|"send updates"| node_max_ingress
node_avito_users -->|"send messages"| node_avito_ingress
node_email_users -->|"send email"| node_email_ingress
node_website_users -->|"send messages"| node_widget_api
node_external_sources -->|"send traffic"| node_external_api
node_telegram_ingress -->|"resolve user"| node_conversation_users
node_telegram_ingress -->|"handle update"| node_telegram_topics
node_telegram_ingress -->|"dispatch AI reply"| node_ai_assistant
node_widget_api -->|"resolve source"| node_external_source_registry
node_widget_api -->|"submit messages"| node_message_history
node_external_api -->|"authenticate source"| node_external_source_registry
node_telegram_topics -->|"record messages"| node_message_history
node_conversation_users -->|"organize history"| node_message_history
node_admin_workspace -->|"manage conversations"| node_message_history
node_telegram_topics -->|"route replies"| node_channel_delivery
node_admin_workspace -->|"send operator replies"| node_channel_delivery
node_ai_assistant -->|"generate answers"| node_ai_delivery
node_ai_delivery -->|"deliver answers"| node_channel_delivery
node_settings -->|"configure routing"| node_telegram_ingress
node_avito_ingress -.->|"handle messages"| node_avito_service
node_email_ingress -.->|"process inbox"| node_email_service
node_vk_ingress -.->|"handle messages"| node_vk_service
node_max_ingress -.->|"handle messages"| node_max_service

click node_telegram_ingress "https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Telegram/Controllers/TelegramBotController.php"
click node_vk_ingress "https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Vk/Controllers/VkBotController.php"
click node_max_ingress "https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Max/Controllers/MaxBotController.php"
click node_avito_ingress "https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Avito/Controllers/AvitoBotController.php"
click node_email_ingress "https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Email/Console/PollInboxCommand.php"
click node_widget_api "https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/External/Controllers/WidgetController.php"
click node_external_api "https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/External/Controllers/ExternalTrafficController.php"
click node_conversation_users "https://github.com/prog-time/tg-support-bot/blob/main/app/Models/BotUser.php"
click node_message_history "https://github.com/prog-time/tg-support-bot/blob/main/app/Models/Message.php"
click node_telegram_topics "https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Telegram/Services/Tg/TgMessageService.php"
click node_admin_workspace "https://github.com/prog-time/tg-support-bot/blob/main/app/Livewire/Chat/ConversationPage.php"
click node_ai_assistant "https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Ai/Services/AiAssistantService.php"
click node_ai_delivery "https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Ai/Actions/DeliverAiAnswerToUser.php"
click node_channel_delivery "https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Telegram/Jobs/SendTelegramMessageJob.php"
click node_settings "https://github.com/prog-time/tg-support-bot/blob/main/app/Services/Settings/SettingsService.php"
click node_external_source_registry "https://github.com/prog-time/tg-support-bot/blob/main/app/Models/ExternalSource.php"
click node_avito_service "https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Avito/Services/AvitoMessageService.php"
click node_email_service "https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Email/Services/EmailMessageService.php"
click node_vk_service "https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Vk/Services/VkMessageService.php"
click node_max_service "https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Max/Services/MaxMessageService.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_telegram_ingress,node_vk_ingress,node_max_ingress,node_avito_ingress,node_email_ingress,node_widget_api,node_external_api,node_telegram_users,node_vk_users,node_max_users,node_avito_users,node_email_users,node_website_users toneBlue
class node_conversation_users,node_message_history,node_telegram_topics toneAmber
class node_admin_workspace,node_ai_assistant,node_ai_delivery,node_external_sources toneMint
class node_channel_delivery,node_settings,node_external_source_registry,node_avito_service,node_email_service,node_vk_service,node_max_service toneRose
```

## Components

### Channels and intake

- [Telegram updates](https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Telegram/Controllers/TelegramBotController.php): `app/Modules/Telegram/Controllers/TelegramBotController.php`
- [VK updates](https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Vk/Controllers/VkBotController.php): `app/Modules/Vk/Controllers/VkBotController.php`
- [Max updates](https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Max/Controllers/MaxBotController.php): `app/Modules/Max/Controllers/MaxBotController.php`
- [Avito updates](https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Avito/Controllers/AvitoBotController.php): `app/Modules/Avito/Controllers/AvitoBotController.php`
- [Email inbox](https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Email/Console/PollInboxCommand.php): `app/Modules/Email/Console/PollInboxCommand.php`
- [Website widget API](https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/External/Controllers/WidgetController.php): `app/Modules/External/Controllers/WidgetController.php`
- [External traffic API](https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/External/Controllers/ExternalTrafficController.php): `app/Modules/External/Controllers/ExternalTrafficController.php`

### Conversation handling

- [Support conversations](https://github.com/prog-time/tg-support-bot/blob/main/app/Models/BotUser.php): `app/Models/BotUser.php`
- [Message history](https://github.com/prog-time/tg-support-bot/blob/main/app/Models/Message.php): `app/Models/Message.php`
- [Telegram group topics](https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Telegram/Services/Tg/TgMessageService.php): `app/Modules/Telegram/Services/Tg/TgMessageService.php`

### Operator workspace

- [Manager chat workspace](https://github.com/prog-time/tg-support-bot/blob/main/app/Livewire/Chat/ConversationPage.php): `app/Livewire/Chat/ConversationPage.php`
- [AI assistant](https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Ai/Services/AiAssistantService.php): `app/Modules/Ai/Services/AiAssistantService.php`
- [AI answer delivery](https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Ai/Actions/DeliverAiAnswerToUser.php): `app/Modules/Ai/Actions/DeliverAiAnswerToUser.php`

### Platform services

- [Channel messaging](https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Telegram/Jobs/SendTelegramMessageJob.php): `app/Modules/Telegram/Jobs/SendTelegramMessageJob.php`
- [Channel settings](https://github.com/prog-time/tg-support-bot/blob/main/app/Services/Settings/SettingsService.php): `app/Services/Settings/SettingsService.php`
- [External source registry](https://github.com/prog-time/tg-support-bot/blob/main/app/Models/ExternalSource.php): `app/Models/ExternalSource.php`
- [Avito messaging](https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Avito/Services/AvitoMessageService.php): `app/Modules/Avito/Services/AvitoMessageService.php`
- [Email messaging](https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Email/Services/EmailMessageService.php): `app/Modules/Email/Services/EmailMessageService.php`
- [VK messaging](https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Vk/Services/VkMessageService.php): `app/Modules/Vk/Services/VkMessageService.php`
- [Max messaging](https://github.com/prog-time/tg-support-bot/blob/main/app/Modules/Max/Services/MaxMessageService.php): `app/Modules/Max/Services/MaxMessageService.php`

### Other components

- **Telegram users**
- **VK users**
- **Max users**
- **Avito users**
- **Email users**
- **Website users**
- **External API sources**

## Connections

- Telegram users → Telegram updates: send updates (evidence: `README.md`)
- VK users → VK updates: send updates (evidence: `README.md`)
- Max users → Max updates: send updates (evidence: `README.md`)
- Avito users → Avito updates: send messages (evidence: `README.md`)
- Email users → Email inbox: send email (evidence: `README.md`)
- Website users → Website widget API: send messages (evidence: `README.md`)
- External API sources → External traffic API: send traffic (evidence: `README.md`)
- Telegram updates → Support conversations: resolve user (evidence: `app/Modules/Telegram/Controllers/TelegramBotController.php`)
- Telegram updates → Telegram group topics: handle update (evidence: `app/Modules/Telegram/Controllers/TelegramBotController.php`)
- Telegram updates → AI assistant: dispatch AI reply (evidence: `app/Modules/Telegram/Controllers/TelegramBotController.php`)
- Website widget API → External source registry: resolve source (evidence: `app/Modules/External/Controllers/WidgetController.php`)
- Website widget API → Message history: submit messages (evidence: `app/Modules/External/Controllers/WidgetController.php`)
- External traffic API → External source registry: authenticate source
- Telegram group topics → Message history: record messages (evidence: `README.md`)
- Support conversations → Message history: organize history (evidence: `app/Models/BotUser.php`)
- Manager chat workspace → Message history: manage conversations (evidence: `README.md`)
- Telegram group topics → Channel messaging: route replies (evidence: `README.md`)
- Manager chat workspace → Channel messaging: send operator replies (evidence: `README.md`)
- AI assistant → AI answer delivery: generate answers (evidence: `app/Modules/Ai/Jobs/SendAiReplyJob.php`)
- AI answer delivery → Channel messaging: deliver answers (evidence: `app/Modules/Ai/Actions/AiAcceptMessage.php`)
- Channel settings → Telegram updates: configure routing (evidence: `app/Modules/Telegram/Controllers/TelegramBotController.php`)
- Avito updates → Avito messaging: handle messages
- Email inbox → Email messaging: process inbox
- VK updates → VK messaging: handle messages
- Max updates → Max messaging: handle messages
