# yuschkof/izhget_bot architecture

> Architecture diagram of the GitHub repository yuschkof/izhget_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/yuschkof/izhget_bot
- Repository: https://github.com/yuschkof/izhget_bot

## Overview

izhGet_bot is a Telegram bot for looking up Izhevsk tram and trolleybus timetables. Its primary workflow takes a user through a time window, route, origin and destination, then fetches and displays matching timetable results; users can also save, rename and manage favorite routes, use them inline, and schedule daily notifications. Handlers own these actions, with shared callback-keyboard factories, SQLite persistence, and an HTTP/HTML timetable parser beneath them. The README documents these capabilities; links are limited to relationships shown in excerpts, the source index, or the README.

Main entry points: [`main.py`](https://github.com/yuschkof/izhget_bot/blob/main/main.py) (Bot runtime), [`db/db.py`](https://github.com/yuschkof/izhget_bot/blob/main/db/db.py) (SQLite data), [`request.py`](https://github.com/yuschkof/izhget_bot/blob/main/request.py) (Timetable parser), [`handlers/new_route.py`](https://github.com/yuschkof/izhget_bot/blob/main/handlers/new_route.py) (Route search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Bot runtime"]
  node_main["Bot runtime<br/>[main.py]"]
  node_middleware["User tracking<br/>[middlewares.py]"]
end

subgraph group_flows["User workflows"]
  node_common["Help and support<br/>[common.py]"]
  node_newroute["Route search<br/>[new_route.py]"]
  node_favorites["Favorite routes<br/>[favorite_route.py]"]
  node_subscriptions["Subscription management<br/>[subscription.py]"]
  node_inline["Inline lookup<br/>[inline.py]"]
  node_admin["Admin tools<br/>[admin.py]"]
end

subgraph group_services["Shared services"]
  node_keyboards["Callback keyboards<br/>[keyboards.py]"]
  node_parser["Timetable parser<br/>[request.py]"]
end

subgraph group_state["Persistence"]
  node_sqlite[("SQLite data<br/>[db.py]")]
end

node_user(("Telegram user"))
node_telegram{{"Telegram API"}}
node_timetable{{"IzhGET timetable site"}}

node_user -->|"sends updates"| node_telegram
node_telegram -->|"polls updates"| node_main
node_main -->|"registers middleware"| node_middleware
node_middleware -->|"registers users"| node_sqlite
node_middleware -->|"tracks activity"| node_sqlite
node_main -->|"includes router"| node_common
node_main -->|"includes router"| node_newroute
node_main -->|"includes router"| node_favorites
node_main -->|"includes router"| node_subscriptions
node_main -->|"includes router"| node_inline
node_main -->|"includes router"| node_admin
node_common -->|"updates statistics"| node_sqlite
node_common -->|"builds keyboard"| node_keyboards
node_common -->|"forwards support"| node_telegram
node_newroute -->|"builds choices"| node_keyboards
node_newroute -->|"loads stops"| node_parser
node_newroute -->|"fetches timetable"| node_parser
node_newroute -->|"saves favorite"| node_sqlite
node_favorites -->|"manages favorites"| node_sqlite
node_favorites -->|"fetches timetable"| node_parser
node_favorites -->|"builds controls"| node_keyboards
node_subscriptions -->|"manages subscriptions"| node_sqlite
node_subscriptions -->|"fetches timetable"| node_parser
node_subscriptions -->|"builds controls"| node_keyboards
node_inline -->|"reads favorites"| node_sqlite
node_inline -->|"fetches timetable"| node_parser
node_admin -->|"lists users"| node_sqlite
node_admin -->|"sends broadcasts"| node_telegram
node_main -->|"initializes and queries"| node_sqlite
node_main -->|"closes parser"| node_parser
node_main -->|"reads due subscriptions"| node_sqlite
node_main -->|"fetches notifications"| node_parser
node_main -->|"sends notifications"| node_telegram
node_parser -->|"posts requests"| node_timetable
node_parser -->|"references data layer"| node_sqlite

click node_main "https://github.com/yuschkof/izhget_bot/blob/main/main.py"
click node_middleware "https://github.com/yuschkof/izhget_bot/blob/main/middlewares.py"
click node_common "https://github.com/yuschkof/izhget_bot/blob/main/handlers/common.py"
click node_newroute "https://github.com/yuschkof/izhget_bot/blob/main/handlers/new_route.py"
click node_favorites "https://github.com/yuschkof/izhget_bot/blob/main/handlers/favorite_route.py"
click node_subscriptions "https://github.com/yuschkof/izhget_bot/blob/main/handlers/subscription.py"
click node_inline "https://github.com/yuschkof/izhget_bot/blob/main/handlers/inline.py"
click node_admin "https://github.com/yuschkof/izhget_bot/blob/main/handlers/admin.py"
click node_keyboards "https://github.com/yuschkof/izhget_bot/blob/main/keyboards/keyboards.py"
click node_parser "https://github.com/yuschkof/izhget_bot/blob/main/request.py"
click node_sqlite "https://github.com/yuschkof/izhget_bot/blob/main/db/db.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_main,node_middleware,node_user toneBlue
class node_common,node_newroute,node_favorites,node_subscriptions,node_inline,node_admin toneAmber
class node_keyboards,node_parser,node_telegram toneMint
class node_sqlite toneRose
class node_timetable toneIndigo
```

## Components

### Bot runtime

- [Bot runtime](https://github.com/yuschkof/izhget_bot/blob/main/main.py): `main.py`
- [User tracking](https://github.com/yuschkof/izhget_bot/blob/main/middlewares.py): `middlewares.py`

### User workflows

- [Help and support](https://github.com/yuschkof/izhget_bot/blob/main/handlers/common.py): `handlers/common.py`
- [Route search](https://github.com/yuschkof/izhget_bot/blob/main/handlers/new_route.py): `handlers/new_route.py`
- [Favorite routes](https://github.com/yuschkof/izhget_bot/blob/main/handlers/favorite_route.py): `handlers/favorite_route.py`
- [Subscription management](https://github.com/yuschkof/izhget_bot/blob/main/handlers/subscription.py): `handlers/subscription.py`
- [Inline lookup](https://github.com/yuschkof/izhget_bot/blob/main/handlers/inline.py): `handlers/inline.py`
- [Admin tools](https://github.com/yuschkof/izhget_bot/blob/main/handlers/admin.py): `handlers/admin.py`

### Shared services

- [Callback keyboards](https://github.com/yuschkof/izhget_bot/blob/main/keyboards/keyboards.py): `keyboards/keyboards.py`
- [Timetable parser](https://github.com/yuschkof/izhget_bot/blob/main/request.py): `request.py`

### Persistence

- [SQLite data](https://github.com/yuschkof/izhget_bot/blob/main/db/db.py): `db/db.py`

### Other components

- **Telegram user**
- **Telegram API**
- **IzhGET timetable site**

## Connections

- Telegram user → Telegram API: sends updates (evidence: `README.md`)
- Telegram API → Bot runtime: polls updates (evidence: `main.py`)
- Bot runtime → User tracking: registers middleware (evidence: `main.py`)
- User tracking → SQLite data: registers users (evidence: `middlewares.py`)
- User tracking → SQLite data: tracks activity (evidence: `middlewares.py`)
- Bot runtime → Help and support: includes router (evidence: `main.py`)
- Bot runtime → Route search: includes router (evidence: `main.py`)
- Bot runtime → Favorite routes: includes router (evidence: `main.py`)
- Bot runtime → Subscription management: includes router (evidence: `main.py`)
- Bot runtime → Inline lookup: includes router (evidence: `main.py`)
- Bot runtime → Admin tools: includes router (evidence: `main.py`)
- Help and support → SQLite data: updates statistics (evidence: `handlers/common.py`)
- Help and support → Callback keyboards: builds keyboard (evidence: `handlers/common.py`)
- Help and support → Telegram API: forwards support (evidence: `handlers/common.py`)
- Route search → Callback keyboards: builds choices (evidence: `handlers/new_route.py`)
- Route search → Timetable parser: loads stops (evidence: `handlers/new_route.py`)
- Route search → Timetable parser: fetches timetable (evidence: `handlers/new_route.py`)
- Route search → SQLite data: saves favorite (evidence: `handlers/new_route.py`)
- Favorite routes → SQLite data: manages favorites (evidence: `handlers/favorite_route.py`)
- Favorite routes → Timetable parser: fetches timetable (evidence: `handlers/favorite_route.py`)
- Favorite routes → Callback keyboards: builds controls (evidence: `handlers/favorite_route.py`)
- Subscription management → SQLite data: manages subscriptions (evidence: `handlers/subscription.py`)
- Subscription management → Timetable parser: fetches timetable (evidence: `handlers/subscription.py`)
- Subscription management → Callback keyboards: builds controls (evidence: `handlers/subscription.py`)
- Inline lookup → SQLite data: reads favorites (evidence: `handlers/inline.py`)
- Inline lookup → Timetable parser: fetches timetable (evidence: `handlers/inline.py`)
- Admin tools → SQLite data: lists users (evidence: `handlers/admin.py`)
- Admin tools → Telegram API: sends broadcasts (evidence: `handlers/admin.py`)
- Bot runtime → SQLite data: initializes and queries (evidence: `main.py`)
- Bot runtime → Timetable parser: closes parser (evidence: `main.py`)
- Bot runtime → SQLite data: reads due subscriptions (evidence: `main.py`)
- Bot runtime → Timetable parser: fetches notifications (evidence: `main.py`)
- Bot runtime → Telegram API: sends notifications (evidence: `main.py`)
- Timetable parser → IzhGET timetable site: posts requests (evidence: `request.py`)
- Timetable parser → SQLite data: references data layer (evidence: `request.py`)
