# andcher03/tg_bot_kddm architecture

> Architecture diagram of the GitHub repository andcher03/tg_bot_kddm, 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/andcher03/tg_bot_kddm
- Repository: https://github.com/andcher03/tg_bot_kddm

## Overview

Молодёжь Казани is a Telegram youth-information bot paired with a FastAPI admin panel and a separate mailing worker. Users browse city resources, register for events, manage profiles and subscriptions, and submit reviews; administrators manage users, events, registrations, reviews, and campaigns. Both interfaces share PostgreSQL. The graph preserves documented product areas whose implementation was not sampled, while omitting uncertain internal links. Edges cite excerpts, SOURCE INDEX references, or README statements; the README establishes several cross-process relationships.

Main entry points: [`services/database.py`](https://github.com/andcher03/tg_bot_kddm/blob/main/services/database.py) (PostgreSQL), [`bot.py`](https://github.com/andcher03/tg_bot_kddm/blob/main/bot.py) (Bot application), [`web_admin/app.py`](https://github.com/andcher03/tg_bot_kddm/blob/main/web_admin/app.py) (Admin application), [`handlers/profile.py`](https://github.com/andcher03/tg_bot_kddm/blob/main/handlers/profile.py) (Profile and registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telegram["Telegram experience"]
  node_bot_entry["Bot application<br/>[bot.py]"]
  node_profile["Profile and registration<br/>[profile.py]"]
  node_event_ui["Event discovery<br/>[afisha.py]"]
  node_city_info["City information<br/>[main_sections.py]"]
  node_youth_orgs["Youth organizations"]
  node_youth_map["Youth map<br/>[youth_map.py]"]
  node_quiz["Quizzes<br/>[quiz.py]"]
  node_subscriptions["User subscriptions<br/>[subscription.py]"]
end

subgraph group_domain["Platform services"]
  node_channel_stats["Channel statistics"]
  node_user_service["User records"]
  node_event_service["Event records"]
  node_registration_service["Event registration"]
  node_review_service["Event reviews<br/>[review_service.py]"]
  node_mailing_service["Mailing subscriptions<br/>[mailing_service.py]"]
end

subgraph group_admin["Web administration"]
  node_admin_app["Admin application<br/>[app.py]"]
  node_admin_auth["Admin authentication<br/>[auth.py]"]
  node_admin_users["User management<br/>[users.py]"]
  node_admin_events["Event management<br/>[events.py]"]
  node_admin_registrations["Registration management<br/>[registrations.py]"]
  node_admin_reviews["Review management<br/>[reviews.py]"]
  node_admin_dashboard["Admin dashboard<br/>[dashboard.py]"]
end

subgraph group_mailing["Campaign delivery"]
  node_admin_mailing["Campaign setup<br/>[mailing.py]"]
  node_mailing_worker["Mailing worker<br/>[mailing_worker.py]"]
  node_mailing_queue["Campaign queue<br/>[mailing_queue.py]"]
  node_telegram_sender["Telegram bot client<br/>[telegram_bot.py]"]
end

subgraph group_storage["Shared state"]
  node_database[("PostgreSQL<br/>[database.py]")]
  node_models["Data models<br/>[models.py]"]
end

node_user(("Telegram user"))
node_telegram_api{{"Telegram API"}}
node_browser(("Administrator"))

node_user -->|"uses"| node_bot_entry
node_bot_entry -->|"dispatches"| node_profile
node_bot_entry -->|"dispatches"| node_event_ui
node_bot_entry -->|"dispatches"| node_city_info
node_bot_entry -->|"dispatches"| node_youth_orgs
node_bot_entry -->|"dispatches"| node_youth_map
node_bot_entry -->|"dispatches"| node_quiz
node_bot_entry -->|"dispatches"| node_subscriptions
node_bot_entry -->|"records stats"| node_channel_stats
node_profile -->|"uses"| node_user_service
node_profile -->|"uses"| node_event_service
node_profile -->|"uses"| node_registration_service
node_profile -->|"uses"| node_review_service
node_profile -->|"manages subscriptions"| node_mailing_service
node_event_ui -->|"searches events"| node_event_service
node_event_ui -->|"registers users"| node_registration_service
node_event_ui -->|"submits reviews"| node_review_service
node_city_info -.->|"offers section"| node_youth_orgs
node_bot_entry -->|"communicates"| node_telegram_api
node_channel_stats -->|"reads membership"| node_telegram_api
node_user_service -->|"reads and writes"| node_database
node_event_service -->|"reads and writes"| node_database
node_registration_service -->|"reads and writes"| node_database
node_review_service -->|"reads and writes"| node_database
node_channel_stats -->|"stores statistics"| node_database
node_database -->|"stores"| node_models
node_browser -->|"uses"| node_admin_app
node_admin_app -->|"applies middleware"| node_admin_auth
node_admin_app -->|"mounts router"| node_admin_users
node_admin_app -->|"mounts router"| node_admin_events
node_admin_app -->|"mounts router"| node_admin_registrations
node_admin_app -->|"mounts router"| node_admin_reviews
node_admin_app -->|"mounts router"| node_admin_dashboard
node_admin_app -->|"mounts router"| node_admin_mailing
node_admin_users -->|"manages users"| node_database
node_admin_events -->|"manages events"| node_database
node_admin_registrations -->|"manages registrations"| node_database
node_admin_reviews -->|"reads reviews"| node_database
node_admin_dashboard -.->|"reads dashboard data"| node_database
node_admin_mailing -->|"selects audience"| node_database
node_admin_mailing -->|"queues campaign"| node_mailing_queue
node_mailing_worker -->|"polls deliveries"| node_mailing_queue
node_mailing_worker -->|"sends messages"| node_telegram_sender
node_telegram_sender -->|"delivers campaign"| node_telegram_api
node_mailing_queue -->|"persists queue"| node_database

click node_bot_entry "https://github.com/andcher03/tg_bot_kddm/blob/main/bot.py"
click node_profile "https://github.com/andcher03/tg_bot_kddm/blob/main/handlers/profile.py"
click node_event_ui "https://github.com/andcher03/tg_bot_kddm/blob/main/handlers/afisha.py"
click node_city_info "https://github.com/andcher03/tg_bot_kddm/blob/main/handlers/main_sections.py"
click node_youth_orgs "https://github.com/andcher03/tg_bot_kddm/blob/main/handlers/youth_organizations.py"
click node_youth_map "https://github.com/andcher03/tg_bot_kddm/blob/main/handlers/youth_map.py"
click node_quiz "https://github.com/andcher03/tg_bot_kddm/blob/main/handlers/quiz.py"
click node_subscriptions "https://github.com/andcher03/tg_bot_kddm/blob/main/handlers/subscription.py"
click node_channel_stats "https://github.com/andcher03/tg_bot_kddm/blob/main/services/channel_stats_service.py"
click node_user_service "https://github.com/andcher03/tg_bot_kddm/blob/main/services/postgres_user_service.py"
click node_event_service "https://github.com/andcher03/tg_bot_kddm/blob/main/services/postgres_event_service.py"
click node_registration_service "https://github.com/andcher03/tg_bot_kddm/blob/main/services/registration_service.py"
click node_review_service "https://github.com/andcher03/tg_bot_kddm/blob/main/services/review_service.py"
click node_mailing_service "https://github.com/andcher03/tg_bot_kddm/blob/main/services/mailing_service.py"
click node_admin_app "https://github.com/andcher03/tg_bot_kddm/blob/main/web_admin/app.py"
click node_admin_auth "https://github.com/andcher03/tg_bot_kddm/blob/main/web_admin/auth.py"
click node_admin_users "https://github.com/andcher03/tg_bot_kddm/blob/main/web_admin/routers/users.py"
click node_admin_events "https://github.com/andcher03/tg_bot_kddm/blob/main/web_admin/routers/events.py"
click node_admin_registrations "https://github.com/andcher03/tg_bot_kddm/blob/main/web_admin/routers/registrations.py"
click node_admin_reviews "https://github.com/andcher03/tg_bot_kddm/blob/main/web_admin/routers/reviews.py"
click node_admin_dashboard "https://github.com/andcher03/tg_bot_kddm/blob/main/web_admin/routers/dashboard.py"
click node_admin_mailing "https://github.com/andcher03/tg_bot_kddm/blob/main/web_admin/routers/mailing.py"
click node_mailing_worker "https://github.com/andcher03/tg_bot_kddm/blob/main/services/mailing_worker.py"
click node_mailing_queue "https://github.com/andcher03/tg_bot_kddm/blob/main/services/mailing_queue.py"
click node_telegram_sender "https://github.com/andcher03/tg_bot_kddm/blob/main/services/telegram_bot.py"
click node_database "https://github.com/andcher03/tg_bot_kddm/blob/main/services/database.py"
click node_models "https://github.com/andcher03/tg_bot_kddm/blob/main/services/models.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_entry,node_profile,node_event_ui,node_city_info,node_youth_orgs,node_youth_map,node_quiz,node_subscriptions,node_user toneBlue
class node_channel_stats,node_user_service,node_event_service,node_registration_service,node_review_service,node_mailing_service toneAmber
class node_admin_app,node_admin_auth,node_admin_users,node_admin_events,node_admin_registrations,node_admin_reviews,node_admin_dashboard,node_telegram_api toneMint
class node_admin_mailing,node_mailing_worker,node_mailing_queue,node_telegram_sender toneRose
class node_database,node_models,node_browser toneIndigo
```

## Components

### Telegram experience

- [Bot application](https://github.com/andcher03/tg_bot_kddm/blob/main/bot.py): `bot.py`
- [Profile and registration](https://github.com/andcher03/tg_bot_kddm/blob/main/handlers/profile.py): `handlers/profile.py`
- [Event discovery](https://github.com/andcher03/tg_bot_kddm/blob/main/handlers/afisha.py): `handlers/afisha.py`
- [City information](https://github.com/andcher03/tg_bot_kddm/blob/main/handlers/main_sections.py): `handlers/main_sections.py`
- [Youth organizations](https://github.com/andcher03/tg_bot_kddm/blob/main/handlers/youth_organizations.py): `handlers/youth_organizations.py`
- [Youth map](https://github.com/andcher03/tg_bot_kddm/blob/main/handlers/youth_map.py): `handlers/youth_map.py`
- [Quizzes](https://github.com/andcher03/tg_bot_kddm/blob/main/handlers/quiz.py): `handlers/quiz.py`
- [User subscriptions](https://github.com/andcher03/tg_bot_kddm/blob/main/handlers/subscription.py): `handlers/subscription.py`

### Platform services

- [Channel statistics](https://github.com/andcher03/tg_bot_kddm/blob/main/services/channel_stats_service.py): `services/channel_stats_service.py`
- [User records](https://github.com/andcher03/tg_bot_kddm/blob/main/services/postgres_user_service.py): `services/postgres_user_service.py`
- [Event records](https://github.com/andcher03/tg_bot_kddm/blob/main/services/postgres_event_service.py): `services/postgres_event_service.py`
- [Event registration](https://github.com/andcher03/tg_bot_kddm/blob/main/services/registration_service.py): `services/registration_service.py`
- [Event reviews](https://github.com/andcher03/tg_bot_kddm/blob/main/services/review_service.py): `services/review_service.py`
- [Mailing subscriptions](https://github.com/andcher03/tg_bot_kddm/blob/main/services/mailing_service.py): `services/mailing_service.py`

### Web administration

- [Admin application](https://github.com/andcher03/tg_bot_kddm/blob/main/web_admin/app.py): `web_admin/app.py`
- [Admin authentication](https://github.com/andcher03/tg_bot_kddm/blob/main/web_admin/auth.py): `web_admin/auth.py`
- [User management](https://github.com/andcher03/tg_bot_kddm/blob/main/web_admin/routers/users.py): `web_admin/routers/users.py`
- [Event management](https://github.com/andcher03/tg_bot_kddm/blob/main/web_admin/routers/events.py): `web_admin/routers/events.py`
- [Registration management](https://github.com/andcher03/tg_bot_kddm/blob/main/web_admin/routers/registrations.py): `web_admin/routers/registrations.py`
- [Review management](https://github.com/andcher03/tg_bot_kddm/blob/main/web_admin/routers/reviews.py): `web_admin/routers/reviews.py`
- [Admin dashboard](https://github.com/andcher03/tg_bot_kddm/blob/main/web_admin/routers/dashboard.py): `web_admin/routers/dashboard.py`

### Campaign delivery

- [Campaign setup](https://github.com/andcher03/tg_bot_kddm/blob/main/web_admin/routers/mailing.py): `web_admin/routers/mailing.py`
- [Mailing worker](https://github.com/andcher03/tg_bot_kddm/blob/main/services/mailing_worker.py): `services/mailing_worker.py`
- [Campaign queue](https://github.com/andcher03/tg_bot_kddm/blob/main/services/mailing_queue.py): `services/mailing_queue.py`
- [Telegram bot client](https://github.com/andcher03/tg_bot_kddm/blob/main/services/telegram_bot.py): `services/telegram_bot.py`

### Shared state

- [PostgreSQL](https://github.com/andcher03/tg_bot_kddm/blob/main/services/database.py): `services/database.py`
- [Data models](https://github.com/andcher03/tg_bot_kddm/blob/main/services/models.py): `services/models.py`

### Other components

- **Telegram user**
- **Telegram API**
- **Administrator**

## Connections

- Telegram user → Bot application: uses
- Bot application → Profile and registration: dispatches (evidence: `bot.py`)
- Bot application → Event discovery: dispatches (evidence: `bot.py`)
- Bot application → City information: dispatches (evidence: `bot.py`)
- Bot application → Youth organizations: dispatches (evidence: `bot.py`)
- Bot application → Youth map: dispatches (evidence: `bot.py`)
- Bot application → Quizzes: dispatches (evidence: `bot.py`)
- Bot application → User subscriptions: dispatches (evidence: `bot.py`)
- Bot application → Channel statistics: records stats (evidence: `bot.py`)
- Profile and registration → User records: uses (evidence: `handlers/profile.py`)
- Profile and registration → Event records: uses (evidence: `handlers/profile.py`)
- Profile and registration → Event registration: uses (evidence: `handlers/profile.py`)
- Profile and registration → Event reviews: uses (evidence: `handlers/profile.py`)
- Profile and registration → Mailing subscriptions: manages subscriptions (evidence: `handlers/profile.py`)
- Event discovery → Event records: searches events (evidence: `handlers/afisha.py`)
- Event discovery → Event registration: registers users (evidence: `handlers/afisha.py`)
- Event discovery → Event reviews: submits reviews (evidence: `handlers/afisha.py`)
- City information → Youth organizations: offers section
- Bot application → Telegram API: communicates
- Channel statistics → Telegram API: reads membership (evidence: `services/channel_stats_service.py`)
- User records → PostgreSQL: reads and writes (evidence: `services/postgres_user_service.py`)
- Event records → PostgreSQL: reads and writes (evidence: `services/postgres_event_service.py`)
- Event registration → PostgreSQL: reads and writes (evidence: `services/registration_service.py`)
- Event reviews → PostgreSQL: reads and writes (evidence: `services/review_service.py`)
- Channel statistics → PostgreSQL: stores statistics (evidence: `services/channel_stats_service.py`)
- PostgreSQL → Data models: stores (evidence: `services/database.py`)
- Administrator → Admin application: uses
- Admin application → Admin authentication: applies middleware (evidence: `web_admin/app.py`)
- Admin application → User management: mounts router (evidence: `web_admin/app.py`)
- Admin application → Event management: mounts router (evidence: `web_admin/app.py`)
- Admin application → Registration management: mounts router (evidence: `web_admin/app.py`)
- Admin application → Review management: mounts router (evidence: `web_admin/app.py`)
- Admin application → Admin dashboard: mounts router (evidence: `web_admin/app.py`)
- Admin application → Campaign setup: mounts router (evidence: `web_admin/app.py`)
- User management → PostgreSQL: manages users
- Event management → PostgreSQL: manages events (evidence: `web_admin/routers/events.py`)
- Registration management → PostgreSQL: manages registrations
- Review management → PostgreSQL: reads reviews (evidence: `web_admin/routers/reviews.py`)
- Admin dashboard → PostgreSQL: reads dashboard data
- Campaign setup → PostgreSQL: selects audience (evidence: `web_admin/routers/mailing.py`)
- Campaign setup → Campaign queue: queues campaign (evidence: `web_admin/routers/mailing.py`)
- Mailing worker → Campaign queue: polls deliveries (evidence: `mailing_worker.py`)
- Mailing worker → Telegram bot client: sends messages (evidence: `mailing_worker.py`)
- Telegram bot client → Telegram API: delivers campaign
- Campaign queue → PostgreSQL: persists queue (evidence: `services/mailing_queue.py`)
