# javohir-g/ttpu-timetable architecture

> Architecture diagram of the GitHub repository javohir-g/ttpu-timetable, 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/javohir-g/ttpu-timetable
- Repository: https://github.com/javohir-g/ttpu-timetable

## Overview

TTPU provides EduPage timetables through two Telegram workflows: a self-service bot for students and teachers, and a one-shot sender for a configured group. A separate mini-app data builder publishes current and upcoming timetable data for a web app, with a service worker supporting offline access. The sampled sources show timetable retrieval, formatting, bot interactions, and caching; the mini-app page implementation and profile persistence details were not sampled, so those links are limited.

Main entry points: [`universal_bot.py`](https://github.com/javohir-g/ttpu-timetable/blob/main/universal_bot.py) (Self-service bot), [`bot.py`](https://github.com/javohir-g/ttpu-timetable/blob/main/bot.py) (One-shot sender), [`miniapp/data.json`](https://github.com/javohir-g/ttpu-timetable/blob/main/miniapp/data.json) (Published timetable data), [`miniapp/build_data.py`](https://github.com/javohir-g/ttpu-timetable/blob/main/miniapp/build_data.py) (Mini-app data builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telegram["Telegram workflows"]
  node_universal_bot["Self-service bot<br/>[universal_bot.py]"]
  node_user_setup["Profile setup<br/>[universal_bot.py]"]
  node_schedule_requests["Schedule requests<br/>[universal_bot.py]"]
  node_single_sender["One-shot sender<br/>[bot.py]"]
end

subgraph group_schedule["Timetable data"]
  node_edupage_data["EduPage timetable retrieval<br/>[universal_bot.py]"]
  node_schedule_cache["Timetable cache<br/>[universal_bot.py]"]
  node_schedule_render["Schedule formatting<br/>[universal_bot.py]"]
  node_fixed_schedule["Fixed-group schedule<br/>[bot.py]"]
end

subgraph group_miniapp["Mini-app"]
  node_data_builder["Mini-app data builder<br/>[build_data.py]"]
  node_miniapp_data["Published timetable data<br/>[data.json]"]
  node_miniapp_page["Mini-app page<br/>[index.html]"]
  node_service_worker["Offline service worker<br/>[sw.js]"]
end

node_user(("Student or teacher"))
node_scheduled_sender(("Scheduled operator"))
node_telegram_api["Telegram API"]
node_edupage_service["EduPage service"]

node_user -->|"sends commands"| node_universal_bot
node_universal_bot -->|"polls and replies"| node_telegram_api
node_universal_bot -->|"handles setup"| node_user_setup
node_user_setup -->|"searches entities"| node_edupage_data
node_universal_bot -->|"routes schedule commands"| node_schedule_requests
node_schedule_requests -->|"loads timetable"| node_schedule_cache
node_schedule_cache -->|"fetches timetable"| node_edupage_service
node_schedule_requests -->|"renders schedule"| node_schedule_render
node_schedule_requests -->|"sends schedule"| node_telegram_api
node_scheduled_sender -->|"runs command"| node_single_sender
node_single_sender -->|"fetches timetable"| node_edupage_service
node_single_sender -->|"builds and formats"| node_fixed_schedule
node_single_sender -->|"sends message"| node_telegram_api
node_data_builder -->|"fetches versions and tables"| node_edupage_service
node_data_builder -->|"writes data"| node_miniapp_data
node_service_worker -->|"caches data"| node_miniapp_data
node_service_worker -->|"caches page"| node_miniapp_page
node_miniapp_page -.->|"reads timetable data"| node_miniapp_data

click node_universal_bot "https://github.com/javohir-g/ttpu-timetable/blob/main/universal_bot.py"
click node_user_setup "https://github.com/javohir-g/ttpu-timetable/blob/main/universal_bot.py"
click node_schedule_requests "https://github.com/javohir-g/ttpu-timetable/blob/main/universal_bot.py"
click node_single_sender "https://github.com/javohir-g/ttpu-timetable/blob/main/bot.py"
click node_edupage_data "https://github.com/javohir-g/ttpu-timetable/blob/main/universal_bot.py"
click node_schedule_cache "https://github.com/javohir-g/ttpu-timetable/blob/main/universal_bot.py"
click node_schedule_render "https://github.com/javohir-g/ttpu-timetable/blob/main/universal_bot.py"
click node_fixed_schedule "https://github.com/javohir-g/ttpu-timetable/blob/main/bot.py"
click node_data_builder "https://github.com/javohir-g/ttpu-timetable/blob/main/miniapp/build_data.py"
click node_miniapp_data "https://github.com/javohir-g/ttpu-timetable/blob/main/miniapp/data.json"
click node_miniapp_page "https://github.com/javohir-g/ttpu-timetable/blob/main/miniapp/index.html"
click node_service_worker "https://github.com/javohir-g/ttpu-timetable/blob/main/miniapp/sw.js"

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_universal_bot,node_user_setup,node_schedule_requests,node_single_sender toneBlue
class node_edupage_data,node_schedule_cache,node_schedule_render,node_fixed_schedule toneAmber
class node_data_builder,node_miniapp_data,node_miniapp_page,node_service_worker,node_telegram_api toneMint
class node_user,node_scheduled_sender,node_edupage_service toneIndigo
```

## Components

### Telegram workflows

- [Self-service bot](https://github.com/javohir-g/ttpu-timetable/blob/main/universal_bot.py): `universal_bot.py`
- [Profile setup](https://github.com/javohir-g/ttpu-timetable/blob/main/universal_bot.py): `universal_bot.py`
- [Schedule requests](https://github.com/javohir-g/ttpu-timetable/blob/main/universal_bot.py): `universal_bot.py`
- [One-shot sender](https://github.com/javohir-g/ttpu-timetable/blob/main/bot.py): `bot.py`

### Timetable data

- [EduPage timetable retrieval](https://github.com/javohir-g/ttpu-timetable/blob/main/universal_bot.py): `universal_bot.py`
- [Timetable cache](https://github.com/javohir-g/ttpu-timetable/blob/main/universal_bot.py): `universal_bot.py`
- [Schedule formatting](https://github.com/javohir-g/ttpu-timetable/blob/main/universal_bot.py): `universal_bot.py`
- [Fixed-group schedule](https://github.com/javohir-g/ttpu-timetable/blob/main/bot.py): `bot.py`

### Mini-app

- [Mini-app data builder](https://github.com/javohir-g/ttpu-timetable/blob/main/miniapp/build_data.py): `miniapp/build_data.py`
- [Published timetable data](https://github.com/javohir-g/ttpu-timetable/blob/main/miniapp/data.json): `miniapp/data.json`
- [Mini-app page](https://github.com/javohir-g/ttpu-timetable/blob/main/miniapp/index.html): `miniapp/index.html`
- [Offline service worker](https://github.com/javohir-g/ttpu-timetable/blob/main/miniapp/sw.js): `miniapp/sw.js`

### Other components

- **Student or teacher**
- **Scheduled operator**
- **Telegram API**
- **EduPage service**

## Connections

- Student or teacher → Self-service bot: sends commands (evidence: `README.md`)
- Self-service bot → Telegram API: polls and replies (evidence: `universal_bot.py`)
- Self-service bot → Profile setup: handles setup (evidence: `universal_bot.py`)
- Profile setup → EduPage timetable retrieval: searches entities (evidence: `universal_bot.py`)
- Self-service bot → Schedule requests: routes schedule commands (evidence: `universal_bot.py`)
- Schedule requests → Timetable cache: loads timetable (evidence: `universal_bot.py`)
- Timetable cache → EduPage service: fetches timetable (evidence: `universal_bot.py`)
- Schedule requests → Schedule formatting: renders schedule (evidence: `universal_bot.py`)
- Schedule requests → Telegram API: sends schedule (evidence: `universal_bot.py`)
- Scheduled operator → One-shot sender: runs command (evidence: `README.md`)
- One-shot sender → EduPage service: fetches timetable (evidence: `bot.py`)
- One-shot sender → Fixed-group schedule: builds and formats (evidence: `bot.py`)
- One-shot sender → Telegram API: sends message (evidence: `bot.py`)
- Mini-app data builder → EduPage service: fetches versions and tables (evidence: `miniapp/build_data.py`)
- Mini-app data builder → Published timetable data: writes data (evidence: `miniapp/build_data.py`)
- Offline service worker → Published timetable data: caches data (evidence: `miniapp/sw.js`)
- Offline service worker → Mini-app page: caches page (evidence: `miniapp/sw.js`)
- Mini-app page → Published timetable data: reads timetable data
