# shlokdhakrey/gbu-timetable-bot architecture

> Architecture diagram of the GitHub repository shlokdhakrey/gbu-timetable-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shlokdhakrey/gbu-timetable-bot
- Repository: https://github.com/shlokdhakrey/gbu-timetable-bot

## Overview

GBU Timetable Bot has two implementations: a Python long-polling bot and an n8n workflow. Students choose a school, program, section, and optional lab batch; the bot then answers timetable queries and sends scheduled summaries and reminders. In Python, bot.py orchestrates message handling and clock ticks, while timetable.py normalizes and caches university data, replies.py routes actions, and reminders.py handles scheduled delivery. The README documents the n8n counterpart; its internal node-level relationships are not represented in the sampled source.

Main entry points: [`reminders.py`](https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/reminders.py) (Scheduled messages), [`bot.py`](https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/bot.py) (Bot loop), [`timetable.py`](https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/timetable.py) (Timetable processing), [`replies.py`](https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/replies.py) (Request routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python_runtime["Python runtime"]
  node_bot["Bot loop<br/>[bot.py]"]
  node_replies["Request routing<br/>[replies.py]"]
  node_messages["Message formatting<br/>[messages.py]"]
  node_telegram_api["Telegram API client<br/>[telegram_api.py]"]
  node_config["Settings<br/>[config.py]"]
end

subgraph group_timetable_domain["Timetable data"]
  node_timetable["Timetable processing<br/>[timetable.py]"]
end

subgraph group_student_state["Student state"]
  node_students[("Student records<br/>[students.py]")]
  node_reminders["Scheduled messages<br/>[reminders.py]"]
  node_sent_state[("Sent-message state")]
end

subgraph group_n8n_runtime["n8n workflow"]
  node_n8n_flow["n8n bot workflow"]
  node_n8n_students[("n8n student table")]
end

node_student(("Student"))
node_clock(("Schedule clock"))
node_gbu_data["GBU timetable sources"]
node_telegram["Telegram service"]

node_student -->|"sends updates"| node_bot
node_clock -->|"triggers checks"| node_bot
node_bot -->|"polls updates"| node_telegram_api
node_bot -->|"dispatches updates"| node_replies
node_bot -->|"runs ticks"| node_reminders
node_bot -->|"refreshes data"| node_timetable
node_replies -->|"reads and updates"| node_students
node_replies -->|"queries classes"| node_timetable
node_replies -->|"builds replies"| node_messages
node_replies -->|"sends replies"| node_telegram_api
node_messages -->|"uses day and time data"| node_timetable
node_reminders -->|"queries classes"| node_timetable
node_reminders -->|"loads recipients"| node_students
node_reminders -->|"formats notices"| node_messages
node_reminders -->|"delivers notices"| node_telegram_api
node_reminders -->|"records deliveries"| node_sent_state
node_timetable -->|"fetches timetable"| node_gbu_data
node_telegram_api -->|"calls Bot API"| node_telegram
node_config -->|"configures sources and periods"| node_timetable
node_config -->|"configures API endpoint"| node_telegram_api
node_student -->|"sends messages"| node_n8n_flow
node_clock -->|"triggers schedule"| node_n8n_flow
node_n8n_flow -->|"reads and saves students"| node_n8n_students
node_n8n_flow -->|"sends bot messages"| node_telegram
node_n8n_flow -->|"fetches timetable"| node_gbu_data

click node_bot "https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/bot.py"
click node_replies "https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/replies.py"
click node_messages "https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/messages.py"
click node_telegram_api "https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/telegram_api.py"
click node_config "https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/config.py"
click node_timetable "https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/timetable.py"
click node_students "https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/students.py"
click node_reminders "https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/reminders.py"
click node_n8n_flow "https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/n8n/gbu-timetable-bot.json"
click node_n8n_students "https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/n8n/gbu-timetable-bot.json"

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_replies,node_messages,node_telegram_api,node_config toneBlue
class node_timetable toneAmber
class node_students,node_reminders,node_sent_state toneMint
class node_n8n_flow,node_n8n_students toneRose
class node_student,node_clock,node_gbu_data,node_telegram toneIndigo
```

## Components

### Python runtime

- [Bot loop](https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/bot.py): `bot.py`
- [Request routing](https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/replies.py): `replies.py`
- [Message formatting](https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/messages.py): `messages.py`
- [Telegram API client](https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/telegram_api.py): `telegram_api.py`
- [Settings](https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/config.py): `config.py`

### Timetable data

- [Timetable processing](https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/timetable.py): `timetable.py`

### Student state

- [Student records](https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/students.py): `students.py`
- [Scheduled messages](https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/reminders.py): `reminders.py`
- **Sent-message state**

### n8n workflow

- [n8n bot workflow](https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/n8n/gbu-timetable-bot.json): `n8n/gbu-timetable-bot.json`
- [n8n student table](https://github.com/shlokdhakrey/gbu-timetable-bot/blob/main/n8n/gbu-timetable-bot.json): `n8n/gbu-timetable-bot.json`

### Other components

- **Student**
- **Schedule clock**
- **GBU timetable sources**
- **Telegram service**

## Connections

- Student → Bot loop: sends updates (evidence: `README.md`)
- Schedule clock → Bot loop: triggers checks (evidence: `README.md`)
- Bot loop → Telegram API client: polls updates (evidence: `bot.py`)
- Bot loop → Request routing: dispatches updates (evidence: `bot.py`)
- Bot loop → Scheduled messages: runs ticks (evidence: `bot.py`)
- Bot loop → Timetable processing: refreshes data (evidence: `bot.py`)
- Request routing → Student records: reads and updates (evidence: `replies.py`)
- Request routing → Timetable processing: queries classes (evidence: `replies.py`)
- Request routing → Message formatting: builds replies (evidence: `replies.py`)
- Request routing → Telegram API client: sends replies (evidence: `replies.py`)
- Message formatting → Timetable processing: uses day and time data (evidence: `messages.py`)
- Scheduled messages → Timetable processing: queries classes (evidence: `reminders.py`)
- Scheduled messages → Student records: loads recipients (evidence: `reminders.py`)
- Scheduled messages → Message formatting: formats notices (evidence: `reminders.py`)
- Scheduled messages → Telegram API client: delivers notices (evidence: `reminders.py`)
- Scheduled messages → Sent-message state: records deliveries (evidence: `reminders.py`)
- Timetable processing → GBU timetable sources: fetches timetable (evidence: `timetable.py`)
- Telegram API client → Telegram service: calls Bot API (evidence: `telegram_api.py`)
- Settings → Timetable processing: configures sources and periods (evidence: `timetable.py`)
- Settings → Telegram API client: configures API endpoint (evidence: `telegram_api.py`)
- Student → n8n bot workflow: sends messages (evidence: `README.md`)
- Schedule clock → n8n bot workflow: triggers schedule (evidence: `README.md`)
- n8n bot workflow → n8n student table: reads and saves students (evidence: `README.md`)
- n8n bot workflow → Telegram service: sends bot messages (evidence: `README.md`)
- n8n bot workflow → GBU timetable sources: fetches timetable (evidence: `README.md`)
