# 6felix9/telegram-gpt architecture

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

- Interactive diagram: https://gitdiagram.com/6felix9/telegram-gpt
- Repository: https://github.com/6felix9/telegram-gpt

## Overview

Telegram GPT Bot listens to chat messages, applies access and activation rules, and routes requests through an agent that can answer from conversation context, images, and web tools. Passive text and voice history, image descriptions, rolling summaries, admin settings, and natural-language schedules are distinct capabilities. The graph shows documented and indexed calls; less-visible scheduler, provider, and transcription wiring is omitted where evidence is insufficient.

Main entry points: [`agent.py`](https://github.com/6felix9/telegram-gpt/blob/main/agent.py) (Agent orchestration), [`handlers/message_handlers.py`](https://github.com/6felix9/telegram-gpt/blob/main/handlers/message_handlers.py) (Message intake), [`database/__init__.py`](https://github.com/6felix9/telegram-gpt/blob/main/database/__init__.py) (Database facade), [`scheduler.py`](https://github.com/6felix9/telegram-gpt/blob/main/scheduler.py) (Schedule runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telegram["Telegram interface"]
  node_bot["Telegram bot runtime<br/>[bot.py]"]
  node_message_handlers["Message intake"]
  node_request_processor["Request processor"]
  node_commands["Admin commands"]
  node_authorization["Access checks<br/>[authorization.py]"]
end

subgraph group_agent["Agent and context"]
  node_agent["Agent orchestration<br/>[agent.py]"]
  node_prompt["Prompt construction<br/>[prompt_builder.py]"]
  node_models["Model selection<br/>[model_registry.py]"]
  node_token_budget["Context trimming<br/>[token_budget.py]"]
  node_summaries["Rolling summaries"]
end

subgraph group_features["Chat capabilities"]
  node_tools["Web tools<br/>[tools.py]"]
  node_images["Image handling<br/>[image_store.py]"]
  node_transcription["Voice transcription<br/>[transcription.py]"]
  node_scheduler["Schedule runner<br/>[scheduler.py]"]
  node_scheduling["Schedule tools<br/>[scheduling.py]"]
end

subgraph group_persistence["Persistence"]
  node_db_facade["Database facade<br/>[__init__.py]"]
  node_messages[("Message history")]
  node_schedule_repo[("Schedule records")]
  node_settings[("Model and access settings")]
  node_connection["PostgreSQL connections<br/>[db_connection.py]"]
end

node_user(("Telegram users"))
node_telegram_service{{"Telegram"}}
node_postgres[("PostgreSQL / Neon")]
node_model_providers{{"Model providers"}}
node_web_search{{"Web search services"}}

node_user -->|"sends messages"| node_telegram_service
node_telegram_service -->|"delivers updates"| node_bot
node_bot -->|"registers handlers"| node_message_handlers
node_bot -->|"starts runner"| node_scheduler
node_message_handlers -->|"checks access"| node_authorization
node_message_handlers -->|"hands off requests"| node_request_processor
node_message_handlers -->|"stores passive messages"| node_db_facade
node_message_handlers -->|"builds chat context"| node_prompt
node_message_handlers -->|"persists images"| node_agent
node_message_handlers -->|"transcribes voice"| node_transcription
node_request_processor -->|"runs requests"| node_agent
node_commands -->|"gates admin actions"| node_authorization
node_commands -->|"clears or switches agent"| node_agent
node_commands -->|"updates settings"| node_db_facade
node_agent -->|"builds system prompt"| node_prompt
node_agent -->|"trims context"| node_token_budget
node_agent -->|"compacts history"| node_summaries
node_agent -->|"binds tools"| node_tools
node_agent -->|"resolves models"| node_models
node_agent -.->|"requests completions"| node_model_providers
node_tools -.->|"searches web"| node_web_search
node_scheduler -->|"runs scheduled prompts"| node_agent
node_scheduler -.->|"loads schedules"| node_db_facade
node_scheduler -.->|"posts results"| node_telegram_service
node_scheduling -->|"creates schedules"| node_db_facade
node_message_handlers -->|"looks up replied images"| node_db_facade
node_db_facade -->|"delegates history"| node_messages
node_db_facade -->|"delegates schedules"| node_schedule_repo
node_db_facade -->|"delegates settings"| node_settings
node_messages -->|"queries through"| node_connection
node_schedule_repo -->|"queries through"| node_connection
node_settings -->|"queries through"| node_connection
node_connection -->|"opens pooled connections"| node_postgres

click node_bot "https://github.com/6felix9/telegram-gpt/blob/main/bot.py"
click node_message_handlers "https://github.com/6felix9/telegram-gpt/blob/main/handlers/message_handlers.py"
click node_request_processor "https://github.com/6felix9/telegram-gpt/blob/main/handlers/request_processor.py"
click node_commands "https://github.com/6felix9/telegram-gpt/blob/main/handlers/command_handlers.py"
click node_authorization "https://github.com/6felix9/telegram-gpt/blob/main/handlers/authorization.py"
click node_agent "https://github.com/6felix9/telegram-gpt/blob/main/agent.py"
click node_prompt "https://github.com/6felix9/telegram-gpt/blob/main/prompt_builder.py"
click node_models "https://github.com/6felix9/telegram-gpt/blob/main/model_registry.py"
click node_token_budget "https://github.com/6felix9/telegram-gpt/blob/main/token_budget.py"
click node_summaries "https://github.com/6felix9/telegram-gpt/blob/main/conversation_summary.py"
click node_tools "https://github.com/6felix9/telegram-gpt/blob/main/tools.py"
click node_images "https://github.com/6felix9/telegram-gpt/blob/main/image_store.py"
click node_transcription "https://github.com/6felix9/telegram-gpt/blob/main/transcription.py"
click node_scheduler "https://github.com/6felix9/telegram-gpt/blob/main/scheduler.py"
click node_scheduling "https://github.com/6felix9/telegram-gpt/blob/main/scheduling.py"
click node_db_facade "https://github.com/6felix9/telegram-gpt/blob/main/database/__init__.py"
click node_messages "https://github.com/6felix9/telegram-gpt/blob/main/database/message_repository.py"
click node_schedule_repo "https://github.com/6felix9/telegram-gpt/blob/main/database/schedule_repository.py"
click node_settings "https://github.com/6felix9/telegram-gpt/blob/main/database/settings_repository.py"
click node_connection "https://github.com/6felix9/telegram-gpt/blob/main/database/db_connection.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,node_message_handlers,node_request_processor,node_commands,node_authorization,node_user toneBlue
class node_agent,node_prompt,node_models,node_token_budget,node_summaries,node_postgres toneAmber
class node_tools,node_images,node_transcription,node_scheduler,node_scheduling toneMint
class node_db_facade,node_messages,node_schedule_repo,node_settings,node_connection toneRose
class node_telegram_service,node_model_providers,node_web_search toneIndigo
```

## Components

### Telegram interface

- [Telegram bot runtime](https://github.com/6felix9/telegram-gpt/blob/main/bot.py): `bot.py`
- [Message intake](https://github.com/6felix9/telegram-gpt/blob/main/handlers/message_handlers.py): `handlers/message_handlers.py`
- [Request processor](https://github.com/6felix9/telegram-gpt/blob/main/handlers/request_processor.py): `handlers/request_processor.py`
- [Admin commands](https://github.com/6felix9/telegram-gpt/blob/main/handlers/command_handlers.py): `handlers/command_handlers.py`
- [Access checks](https://github.com/6felix9/telegram-gpt/blob/main/handlers/authorization.py): `handlers/authorization.py`

### Agent and context

- [Agent orchestration](https://github.com/6felix9/telegram-gpt/blob/main/agent.py): `agent.py`
- [Prompt construction](https://github.com/6felix9/telegram-gpt/blob/main/prompt_builder.py): `prompt_builder.py`
- [Model selection](https://github.com/6felix9/telegram-gpt/blob/main/model_registry.py): `model_registry.py`
- [Context trimming](https://github.com/6felix9/telegram-gpt/blob/main/token_budget.py): `token_budget.py`
- [Rolling summaries](https://github.com/6felix9/telegram-gpt/blob/main/conversation_summary.py): `conversation_summary.py`

### Chat capabilities

- [Web tools](https://github.com/6felix9/telegram-gpt/blob/main/tools.py): `tools.py`
- [Image handling](https://github.com/6felix9/telegram-gpt/blob/main/image_store.py): `image_store.py`
- [Voice transcription](https://github.com/6felix9/telegram-gpt/blob/main/transcription.py): `transcription.py`
- [Schedule runner](https://github.com/6felix9/telegram-gpt/blob/main/scheduler.py): `scheduler.py`
- [Schedule tools](https://github.com/6felix9/telegram-gpt/blob/main/scheduling.py): `scheduling.py`

### Persistence

- [Database facade](https://github.com/6felix9/telegram-gpt/blob/main/database/__init__.py): `database/__init__.py`
- [Message history](https://github.com/6felix9/telegram-gpt/blob/main/database/message_repository.py): `database/message_repository.py`
- [Schedule records](https://github.com/6felix9/telegram-gpt/blob/main/database/schedule_repository.py): `database/schedule_repository.py`
- [Model and access settings](https://github.com/6felix9/telegram-gpt/blob/main/database/settings_repository.py): `database/settings_repository.py`
- [PostgreSQL connections](https://github.com/6felix9/telegram-gpt/blob/main/database/db_connection.py): `database/db_connection.py`

### Other components

- **Telegram users**
- **Telegram**
- **PostgreSQL / Neon**
- **Model providers**
- **Web search services**

## Connections

- Telegram users → Telegram: sends messages (evidence: `README.md`)
- Telegram → Telegram bot runtime: delivers updates (evidence: `bot.py`)
- Telegram bot runtime → Message intake: registers handlers (evidence: `bot.py`)
- Telegram bot runtime → Schedule runner: starts runner (evidence: `bot.py`)
- Message intake → Access checks: checks access (evidence: `handlers/message_handlers.py`)
- Message intake → Request processor: hands off requests (evidence: `handlers/message_handlers.py`)
- Message intake → Database facade: stores passive messages (evidence: `handlers/message_handlers.py`)
- Message intake → Prompt construction: builds chat context (evidence: `handlers/message_handlers.py`)
- Message intake → Agent orchestration: persists images (evidence: `handlers/message_handlers.py`)
- Message intake → Voice transcription: transcribes voice (evidence: `handlers/message_handlers.py`)
- Request processor → Agent orchestration: runs requests (evidence: `handlers/request_processor.py`)
- Admin commands → Access checks: gates admin actions (evidence: `handlers/command_handlers.py`)
- Admin commands → Agent orchestration: clears or switches agent (evidence: `handlers/command_handlers.py`)
- Admin commands → Database facade: updates settings (evidence: `handlers/command_handlers.py`)
- Agent orchestration → Prompt construction: builds system prompt (evidence: `agent.py`)
- Agent orchestration → Context trimming: trims context (evidence: `agent.py`)
- Agent orchestration → Rolling summaries: compacts history (evidence: `agent.py`)
- Agent orchestration → Web tools: binds tools (evidence: `agent.py`)
- Agent orchestration → Model selection: resolves models (evidence: `agent.py`)
- Agent orchestration → Model providers: requests completions
- Web tools → Web search services: searches web
- Schedule runner → Agent orchestration: runs scheduled prompts (evidence: `scheduler.py`)
- Schedule runner → Database facade: loads schedules
- Schedule runner → Telegram: posts results
- Schedule tools → Database facade: creates schedules (evidence: `scheduling.py`)
- Message intake → Database facade: looks up replied images (evidence: `handlers/message_handlers.py`)
- Database facade → Message history: delegates history (evidence: `database/__init__.py`)
- Database facade → Schedule records: delegates schedules (evidence: `database/__init__.py`)
- Database facade → Model and access settings: delegates settings (evidence: `database/__init__.py`)
- Message history → PostgreSQL connections: queries through (evidence: `database/message_repository.py`)
- Schedule records → PostgreSQL connections: queries through (evidence: `database/schedule_repository.py`)
- Model and access settings → PostgreSQL connections: queries through (evidence: `database/settings_repository.py`)
- PostgreSQL connections → PostgreSQL / Neon: opens pooled connections (evidence: `database/db_connection.py`)
