# callmemathew/telegram-bot architecture

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

- Interactive diagram: https://gitdiagram.com/callmemathew/telegram-bot
- Repository: https://github.com/callmemathew/telegram-bot

## Overview

This is a Telegram live-support bot: a user selects a language, sends a message, and chats through a per-user topic in the managers’ forum. The webhook entry point routes updates to handlers, which delegate support behavior to services; SQLite persists user/session metadata and message records. The graph includes documented status, session, and language-UI capabilities, but some implementation details are unsampled, so those links are marked unverified rather than asserted as source-confirmed.

Main entry points: [`internal/config/app/app.go`](https://github.com/callmemathew/telegram-bot/blob/main/internal/config/app/app.go) (Webhook application), [`internal/config/service/service.go`](https://github.com/callmemathew/telegram-bot/blob/main/internal/config/service/service.go) (Support service), [`internal/config/handlers/callback.go`](https://github.com/callmemathew/telegram-bot/blob/main/internal/config/handlers/callback.go) (Language callbacks), [`internal/config/service/flow_user.go`](https://github.com/callmemathew/telegram-bot/blob/main/internal/config/service/flow_user.go) (User-to-manager routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_bootstrap["Bot bootstrap<br/>[main.go]"]
  node_configuration["Runtime configuration<br/>[config.go]"]
  node_app["Webhook application<br/>[app.go]"]
end

subgraph group_interaction["Telegram interaction"]
  node_handlers["Update router<br/>[handlers.go]"]
  node_language_handler["Language callbacks<br/>[callback.go]"]
  node_message_handler["Private message handling<br/>[user.go]"]
  node_handler_texts["Menu and response text<br/>[texts.go]"]
end

subgraph group_support["Support workflows"]
  node_support_service["Support service<br/>[service.go]"]
  node_user_setup["User and language setup<br/>[user.go]"]
  node_user_flow["User-to-manager routing<br/>[flow_user.go]"]
  node_manager_flow["Manager-to-user routing<br/>[flow_manager.go]"]
  node_session_flow["Session status<br/>[flow_manager.go]"]
  node_language_ui["Language UI refresh<br/>[ui_lang.go]"]
  node_language_menu["Language menu<br/>[lang_menu.go]"]
  node_start_hint["Start guidance<br/>[start_hint.go]"]
  node_pinned_card["Manager info card<br/>[pinned_card.go]"]
  node_support_helpers["Message and topic helpers<br/>[helpers.go]"]
end

subgraph group_persistence["Persistent data"]
  node_sqlite_store[("SQLite store<br/>[store.go]")]
  node_user_records["User and session records<br/>[users.go]"]
  node_message_records["Message history<br/>[messages.go]"]
end

node_operator(("User or manager"))
node_telegram["Telegram API"]

node_operator -->|"sends updates"| node_telegram
node_telegram -->|"delivers webhook"| node_app
node_bootstrap -->|"loads settings"| node_configuration
node_bootstrap -->|"starts application"| node_app
node_configuration -->|"configures"| node_app
node_app -->|"opens and initializes"| node_sqlite_store
node_app -->|"constructs"| node_support_service
node_app -->|"constructs and dispatches"| node_handlers
node_handlers -->|"routes callbacks"| node_language_handler
node_handlers -->|"routes messages"| node_message_handler
node_message_handler -.->|"handles user messages"| node_support_service
node_language_handler -->|"updates language and UI"| node_support_service
node_language_handler -->|"sends language text"| node_handler_texts
node_support_service -.->|"delegates setup"| node_user_setup
node_support_service -.->|"delegates routing"| node_user_flow
node_support_service -.->|"delegates routing"| node_manager_flow
node_user_flow -->|"reads and saves"| node_sqlite_store
node_manager_flow -->|"looks up and saves"| node_sqlite_store
node_user_flow -->|"creates topic and forwards"| node_telegram
node_manager_flow -->|"relays replies"| node_telegram
node_language_handler -->|"persists language"| node_user_records
node_user_flow -->|"refreshes card"| node_pinned_card
node_user_flow -->|"uses topic and media helpers"| node_support_helpers
node_manager_flow -->|"uses media helpers"| node_support_helpers
node_language_handler -->|"refreshes interface"| node_language_ui
node_language_menu -.->|"presents choices"| node_telegram
node_start_hint -.->|"shows guidance"| node_telegram
node_session_flow -.->|"updates user status"| node_telegram
node_sqlite_store -->|"stores user state"| node_user_records
node_sqlite_store -->|"stores message history"| node_message_records
node_user_records --> node_message_records

click node_bootstrap "https://github.com/callmemathew/telegram-bot/blob/main/cmd/bot/main.go"
click node_configuration "https://github.com/callmemathew/telegram-bot/blob/main/internal/config/config.go"
click node_app "https://github.com/callmemathew/telegram-bot/blob/main/internal/config/app/app.go"
click node_handlers "https://github.com/callmemathew/telegram-bot/blob/main/internal/config/handlers/handlers.go"
click node_language_handler "https://github.com/callmemathew/telegram-bot/blob/main/internal/config/handlers/callback.go"
click node_message_handler "https://github.com/callmemathew/telegram-bot/blob/main/internal/config/handlers/user.go"
click node_handler_texts "https://github.com/callmemathew/telegram-bot/blob/main/internal/config/handlers/texts.go"
click node_support_service "https://github.com/callmemathew/telegram-bot/blob/main/internal/config/service/service.go"
click node_user_setup "https://github.com/callmemathew/telegram-bot/blob/main/internal/config/service/user.go"
click node_user_flow "https://github.com/callmemathew/telegram-bot/blob/main/internal/config/service/flow_user.go"
click node_manager_flow "https://github.com/callmemathew/telegram-bot/blob/main/internal/config/service/flow_manager.go"
click node_session_flow "https://github.com/callmemathew/telegram-bot/blob/main/internal/config/service/flow_manager.go"
click node_language_ui "https://github.com/callmemathew/telegram-bot/blob/main/internal/config/service/ui_lang.go"
click node_language_menu "https://github.com/callmemathew/telegram-bot/blob/main/internal/config/service/lang_menu.go"
click node_start_hint "https://github.com/callmemathew/telegram-bot/blob/main/internal/config/service/start_hint.go"
click node_pinned_card "https://github.com/callmemathew/telegram-bot/blob/main/internal/config/service/pinned_card.go"
click node_support_helpers "https://github.com/callmemathew/telegram-bot/blob/main/internal/config/service/helpers.go"
click node_sqlite_store "https://github.com/callmemathew/telegram-bot/blob/main/internal/config/storage/store.go"
click node_user_records "https://github.com/callmemathew/telegram-bot/blob/main/internal/config/storage/users.go"
click node_message_records "https://github.com/callmemathew/telegram-bot/blob/main/internal/config/storage/messages.go"

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_bootstrap,node_configuration,node_app,node_operator toneBlue
class node_handlers,node_language_handler,node_message_handler,node_handler_texts toneAmber
class node_support_service,node_user_setup,node_user_flow,node_manager_flow,node_session_flow,node_language_ui,node_language_menu,node_start_hint,node_pinned_card,node_support_helpers,node_telegram toneMint
class node_sqlite_store,node_user_records,node_message_records toneRose
```

## Components

### Application entry

- [Bot bootstrap](https://github.com/callmemathew/telegram-bot/blob/main/cmd/bot/main.go): `cmd/bot/main.go`
- [Runtime configuration](https://github.com/callmemathew/telegram-bot/blob/main/internal/config/config.go): `internal/config/config.go`
- [Webhook application](https://github.com/callmemathew/telegram-bot/blob/main/internal/config/app/app.go): `internal/config/app/app.go`

### Telegram interaction

- [Update router](https://github.com/callmemathew/telegram-bot/blob/main/internal/config/handlers/handlers.go): `internal/config/handlers/handlers.go`
- [Language callbacks](https://github.com/callmemathew/telegram-bot/blob/main/internal/config/handlers/callback.go): `internal/config/handlers/callback.go`
- [Private message handling](https://github.com/callmemathew/telegram-bot/blob/main/internal/config/handlers/user.go): `internal/config/handlers/user.go`
- [Menu and response text](https://github.com/callmemathew/telegram-bot/blob/main/internal/config/handlers/texts.go): `internal/config/handlers/texts.go`

### Support workflows

- [Support service](https://github.com/callmemathew/telegram-bot/blob/main/internal/config/service/service.go): `internal/config/service/service.go`
- [User and language setup](https://github.com/callmemathew/telegram-bot/blob/main/internal/config/service/user.go): `internal/config/service/user.go`
- [User-to-manager routing](https://github.com/callmemathew/telegram-bot/blob/main/internal/config/service/flow_user.go): `internal/config/service/flow_user.go`
- [Manager-to-user routing](https://github.com/callmemathew/telegram-bot/blob/main/internal/config/service/flow_manager.go): `internal/config/service/flow_manager.go`
- [Session status](https://github.com/callmemathew/telegram-bot/blob/main/internal/config/service/flow_manager.go): `internal/config/service/flow_manager.go`
- [Language UI refresh](https://github.com/callmemathew/telegram-bot/blob/main/internal/config/service/ui_lang.go): `internal/config/service/ui_lang.go`
- [Language menu](https://github.com/callmemathew/telegram-bot/blob/main/internal/config/service/lang_menu.go): `internal/config/service/lang_menu.go`
- [Start guidance](https://github.com/callmemathew/telegram-bot/blob/main/internal/config/service/start_hint.go): `internal/config/service/start_hint.go`
- [Manager info card](https://github.com/callmemathew/telegram-bot/blob/main/internal/config/service/pinned_card.go): `internal/config/service/pinned_card.go`
- [Message and topic helpers](https://github.com/callmemathew/telegram-bot/blob/main/internal/config/service/helpers.go): `internal/config/service/helpers.go`

### Persistent data

- [SQLite store](https://github.com/callmemathew/telegram-bot/blob/main/internal/config/storage/store.go): `internal/config/storage/store.go`
- [User and session records](https://github.com/callmemathew/telegram-bot/blob/main/internal/config/storage/users.go): `internal/config/storage/users.go`
- [Message history](https://github.com/callmemathew/telegram-bot/blob/main/internal/config/storage/messages.go): `internal/config/storage/messages.go`

### Other components

- **User or manager**
- **Telegram API**

## Connections

- User or manager → Telegram API: sends updates (evidence: `README.md`)
- Telegram API → Webhook application: delivers webhook (evidence: `internal/config/app/app.go`)
- Bot bootstrap → Runtime configuration: loads settings (evidence: `cmd/bot/main.go`)
- Bot bootstrap → Webhook application: starts application (evidence: `cmd/bot/main.go`)
- Runtime configuration → Webhook application: configures (evidence: `internal/config/app/app.go`)
- Webhook application → SQLite store: opens and initializes (evidence: `internal/config/app/app.go`)
- Webhook application → Support service: constructs (evidence: `internal/config/app/app.go`)
- Webhook application → Update router: constructs and dispatches (evidence: `internal/config/app/app.go`)
- Update router → Language callbacks: routes callbacks (evidence: `internal/config/handlers/handlers.go`)
- Update router → Private message handling: routes messages (evidence: `internal/config/handlers/handlers.go`)
- Private message handling → Support service: handles user messages
- Language callbacks → Support service: updates language and UI (evidence: `internal/config/handlers/callback.go`)
- Language callbacks → Menu and response text: sends language text (evidence: `internal/config/handlers/callback.go`)
- Support service → User and language setup: delegates setup
- Support service → User-to-manager routing: delegates routing
- Support service → Manager-to-user routing: delegates routing
- User-to-manager routing → SQLite store: reads and saves (evidence: `internal/config/service/flow_user.go`)
- Manager-to-user routing → SQLite store: looks up and saves (evidence: `internal/config/service/flow_manager.go`)
- User-to-manager routing → Telegram API: creates topic and forwards (evidence: `internal/config/service/flow_user.go`)
- Manager-to-user routing → Telegram API: relays replies (evidence: `internal/config/service/flow_manager.go`)
- Language callbacks → User and session records: persists language (evidence: `internal/config/handlers/callback.go`)
- User-to-manager routing → Manager info card: refreshes card (evidence: `internal/config/service/flow_user.go`)
- User-to-manager routing → Message and topic helpers: uses topic and media helpers (evidence: `internal/config/service/flow_user.go`)
- Manager-to-user routing → Message and topic helpers: uses media helpers (evidence: `internal/config/service/flow_manager.go`)
- Language callbacks → Language UI refresh: refreshes interface (evidence: `internal/config/handlers/callback.go`)
- Language menu → Telegram API: presents choices (evidence: `README.md`)
- Start guidance → Telegram API: shows guidance (evidence: `README.md`)
- Session status → Telegram API: updates user status (evidence: `README.md`)
- SQLite store → User and session records: stores user state (evidence: `internal/config/storage/users.go`)
- SQLite store → Message history: stores message history (evidence: `internal/config/storage/messages.go`)
- User and session records → Message history
