# rcbtst/video_stats_tg_bot architecture

> Architecture diagram of the GitHub repository rcbtst/video_stats_tg_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/rcbtst/video_stats_tg_bot
- Repository: https://github.com/rcbtst/video_stats_tg_bot

## Overview

This is a Telegram bot that answers Russian-language questions about video statistics. A message handler passes the question to a use case, which invokes a Pydantic AI processor; the processor supplies database schema and current time to the LLM, validates generated SQL, executes it, and returns a numeric result to the bot. The README documents the retry-on-error behavior. The graph includes the database and logging layers; some composition details are supported by indexed references rather than excerpts.

Main entry points: [`src/infrastructure/llm/pydantic_ai_text_question_processor.py`](https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/infrastructure/llm/pydantic_ai_text_question_processor.py) (AI question processor), [`src/interfaces/telegram_bot/handlers/messages.py`](https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/interfaces/telegram_bot/handlers/messages.py) (Message handler), [`src/infrastructure/di_config.py`](https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/infrastructure/di_config.py) (Dependency wiring), [`src/interfaces/telegram_bot/__init__.py`](https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/interfaces/telegram_bot/__init__.py) (Bot runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bot["Telegram interface"]
  node_telegram["Bot runtime<br/>[__init__.py]"]
  node_messages["Message handler<br/>[messages.py]"]
end

subgraph group_app["Question processing"]
  node_command["Question contract"]
  node_usecase["Question use case"]
  node_processor["AI question processor"]
end

subgraph group_infra["Query infrastructure"]
  node_schema_provider["Schema provider"]
  node_query_checker["SQL checker"]
  node_query_executor["Scalar query executor"]
  node_database["SQLAlchemy database"]
  node_video["Video schema<br/>[video.py]"]
  node_snapshots["Snapshot schema<br/>[video_snapshot.py]"]
end

subgraph group_ops["Configuration and logging"]
  node_settings["Environment settings<br/>[config.py]"]
  node_di["Dependency wiring<br/>[di_config.py]"]
  node_logging["Logging adapters<br/>[stdlib_logger.py]"]
end

node_user(("Telegram user"))
node_openrouter{{"OpenRouter LLM"}}
node_postgres[("PostgreSQL")]

node_user -->|"sends message"| node_telegram
node_telegram -->|"routes messages"| node_messages
node_messages -->|"invokes"| node_usecase
node_messages -->|"creates command"| node_command
node_usecase -->|"processes question"| node_processor
node_processor -->|"requests generation"| node_openrouter
node_processor -->|"gets schema"| node_schema_provider
node_schema_provider -->|"describes tables"| node_video
node_schema_provider -->|"describes tables"| node_snapshots
node_processor -->|"validates SQL"| node_query_checker
node_query_checker -->|"allows table"| node_video
node_query_checker -->|"allows table"| node_snapshots
node_processor -->|"executes SQL"| node_query_executor
node_query_executor -->|"runs scalar query"| node_postgres
node_database -->|"opens connection"| node_postgres
node_di -->|"constructs"| node_usecase
node_di -->|"constructs"| node_processor
node_di -->|"configures"| node_database
node_settings -->|"provides settings"| node_di
node_telegram -->|"loads token"| node_settings
node_processor -.->|"logs activity"| node_logging
node_messages -->|"returns answer"| node_user

click node_telegram "https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/interfaces/telegram_bot/__init__.py"
click node_messages "https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/interfaces/telegram_bot/handlers/messages.py"
click node_command "https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/application/contracts/process_text_question.py"
click node_usecase "https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/application/use_cases/process_text_question.py"
click node_processor "https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/infrastructure/llm/pydantic_ai_text_question_processor.py"
click node_schema_provider "https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/infrastructure/database/sqlalchemy_schema_description_provider.py"
click node_query_checker "https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/infrastructure/database/sqlglot_query_checker.py"
click node_query_executor "https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/infrastructure/database/sqlalchemy_db_query_executor.py"
click node_database "https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/infrastructure/database/sqlalchemy_database.py"
click node_video "https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/infrastructure/database/schema/video.py"
click node_snapshots "https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/infrastructure/database/schema/video_snapshot.py"
click node_settings "https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/config.py"
click node_di "https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/infrastructure/di_config.py"
click node_logging "https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/infrastructure/utils/stdlib_logger.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_telegram,node_messages,node_user toneBlue
class node_command,node_usecase,node_processor,node_postgres toneAmber
class node_schema_provider,node_query_checker,node_query_executor,node_database,node_video,node_snapshots,node_openrouter toneMint
class node_settings,node_di,node_logging toneRose
```

## Components

### Telegram interface

- [Bot runtime](https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/interfaces/telegram_bot/__init__.py): `src/interfaces/telegram_bot/__init__.py`
- [Message handler](https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/interfaces/telegram_bot/handlers/messages.py): `src/interfaces/telegram_bot/handlers/messages.py`

### Question processing

- [Question contract](https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/application/contracts/process_text_question.py): `src/application/contracts/process_text_question.py`
- [Question use case](https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/application/use_cases/process_text_question.py): `src/application/use_cases/process_text_question.py`
- [AI question processor](https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/infrastructure/llm/pydantic_ai_text_question_processor.py): `src/infrastructure/llm/pydantic_ai_text_question_processor.py`

### Query infrastructure

- [Schema provider](https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/infrastructure/database/sqlalchemy_schema_description_provider.py): `src/infrastructure/database/sqlalchemy_schema_description_provider.py`
- [SQL checker](https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/infrastructure/database/sqlglot_query_checker.py): `src/infrastructure/database/sqlglot_query_checker.py`
- [Scalar query executor](https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/infrastructure/database/sqlalchemy_db_query_executor.py): `src/infrastructure/database/sqlalchemy_db_query_executor.py`
- [SQLAlchemy database](https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/infrastructure/database/sqlalchemy_database.py): `src/infrastructure/database/sqlalchemy_database.py`
- [Video schema](https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/infrastructure/database/schema/video.py): `src/infrastructure/database/schema/video.py`
- [Snapshot schema](https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/infrastructure/database/schema/video_snapshot.py): `src/infrastructure/database/schema/video_snapshot.py`

### Configuration and logging

- [Environment settings](https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/config.py): `src/config.py`
- [Dependency wiring](https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/infrastructure/di_config.py): `src/infrastructure/di_config.py`
- [Logging adapters](https://github.com/rcbtst/video_stats_tg_bot/blob/main/src/infrastructure/utils/stdlib_logger.py): `src/infrastructure/utils/stdlib_logger.py`

### Other components

- **Telegram user**
- **OpenRouter LLM**
- **PostgreSQL**

## Connections

- Telegram user → Bot runtime: sends message (evidence: `README.md`)
- Bot runtime → Message handler: routes messages (evidence: `src/interfaces/telegram_bot/__init__.py`)
- Message handler → Question use case: invokes (evidence: `src/interfaces/telegram_bot/handlers/messages.py`)
- Message handler → Question contract: creates command (evidence: `src/interfaces/telegram_bot/handlers/messages.py`)
- Question use case → AI question processor: processes question (evidence: `src/application/use_cases/process_text_question.py`)
- AI question processor → OpenRouter LLM: requests generation (evidence: `src/infrastructure/llm/pydantic_ai_text_question_processor.py`)
- AI question processor → Schema provider: gets schema (evidence: `src/infrastructure/llm/pydantic_ai_text_question_processor.py`)
- Schema provider → Video schema: describes tables (evidence: `src/infrastructure/database/sqlalchemy_schema_description_provider.py`)
- Schema provider → Snapshot schema: describes tables (evidence: `src/infrastructure/database/sqlalchemy_schema_description_provider.py`)
- AI question processor → SQL checker: validates SQL (evidence: `src/infrastructure/llm/pydantic_ai_text_question_processor.py`)
- SQL checker → Video schema: allows table (evidence: `src/infrastructure/database/sqlglot_query_checker.py`)
- SQL checker → Snapshot schema: allows table (evidence: `src/infrastructure/database/sqlglot_query_checker.py`)
- AI question processor → Scalar query executor: executes SQL (evidence: `src/infrastructure/llm/pydantic_ai_text_question_processor.py`)
- Scalar query executor → PostgreSQL: runs scalar query (evidence: `src/infrastructure/database/sqlalchemy_db_query_executor.py`)
- SQLAlchemy database → PostgreSQL: opens connection (evidence: `src/infrastructure/database/sqlalchemy_database.py`)
- Dependency wiring → Question use case: constructs (evidence: `src/infrastructure/di_config.py`)
- Dependency wiring → AI question processor: constructs (evidence: `src/infrastructure/di_config.py`)
- Dependency wiring → SQLAlchemy database: configures (evidence: `src/infrastructure/di_config.py`)
- Environment settings → Dependency wiring: provides settings (evidence: `src/infrastructure/di_config.py`)
- Bot runtime → Environment settings: loads token (evidence: `src/interfaces/telegram_bot/__init__.py`)
- AI question processor → Logging adapters: logs activity
- Message handler → Telegram user: returns answer (evidence: `src/interfaces/telegram_bot/handlers/messages.py`)
