# itwistiks/physics_bot architecture

> Architecture diagram of the GitHub repository itwistiks/physics_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/itwistiks/physics_bot
- Repository: https://github.com/itwistiks/physics_bot

## Overview

Physics Bot is a Telegram study bot for OGE physics practice. Students choose a practice mode—random tasks, exam part, full variant, topic, or difficult tasks—then receive tasks, submit answers, and see results; the bot also tracks progress and awards achievements. Administrative handlers manage statistics and reminders, while scheduled jobs send inactivity reminders. The graph follows documented handler and service references; some README-described capabilities are included despite incomplete source excerpts, so their internal wiring is left unspecified where not evidenced.

Main entry points: [`core/handlers/inline_handlers.py`](https://github.com/itwistiks/physics_bot/blob/main/core/handlers/inline_handlers.py) (Task callback handlers), [`core/handlers/reply_handlers.py`](https://github.com/itwistiks/physics_bot/blob/main/core/handlers/reply_handlers.py) (Menu and practice handlers), [`core/services/reminder_service.py`](https://github.com/itwistiks/physics_bot/blob/main/core/services/reminder_service.py) (Inactivity reminders), [`core/database/models.py`](https://github.com/itwistiks/physics_bot/blob/main/core/database/models.py) (Learning and user models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Telegram interaction"]
  node_bot["Bot startup and routing<br/>[bot.py]"]
  node_reply_handlers["Menu and practice handlers<br/>[reply_handlers.py]"]
  node_inline_handlers["Task callback handlers<br/>[inline_handlers.py]"]
  node_keyboards["Practice keyboards<br/>[reply.py]"]
  node_inline_keyboards["Answer keyboards<br/>[inline.py]"]
  node_fsm["Practice state<br/>[states.py]"]
end

subgraph group_learning["Practice and learning"]
  node_task_display["Task presentation<br/>[task_display.py]"]
  node_task_service["Task selection and checking<br/>[task_service.py]"]
  node_task_utils["Task query utilities<br/>[task_utils.py]"]
  node_answer_checker["Answer evaluation<br/>[answer_checker.py]"]
  node_answer_processing["Answer processing"]
end

subgraph group_progress["Progress and rewards"]
  node_user_service["User records<br/>[user_service.py]"]
  node_stats_service["Progress and statistics<br/>[stats_service.py]"]
  node_achievement_service["Achievements and rewards"]
end

subgraph group_operations["Administration and reminders"]
  node_admin_handlers["Admin controls<br/>[admin.py]"]
  node_staff_handlers["Teacher and moderator controls<br/>[teacher.py]"]
  node_admin_filter["Staff authorization<br/>[admin.py]"]
  node_reminder_service["Inactivity reminders"]
  node_reminder_scheduler["Reminder scheduler"]
  node_reminder_jobs["Reminder jobs<br/>[reminder_jobs.py]"]
end

subgraph group_persistence["Persistence"]
  node_models["Learning and user models<br/>[models.py]"]
  node_database[("MySQL session and engine<br/>[database.py]")]
end

node_student(("Student"))
node_telegram["Telegram Bot API"]

node_student -->|"sends requests"| node_telegram
node_bot -->|"serves updates"| node_telegram
node_bot -->|"registers routes"| node_reply_handlers
node_bot -->|"registers routes"| node_inline_handlers
node_bot -->|"starts scheduler"| node_reminder_scheduler
node_reply_handlers -->|"presents menus"| node_keyboards
node_reply_handlers -->|"displays tasks"| node_task_display
node_reply_handlers -->|"queries tasks"| node_task_utils
node_reply_handlers -->|"uses task service"| node_task_service
node_reply_handlers -->|"loads statistics"| node_stats_service
node_inline_handlers -->|"displays tasks"| node_task_display
node_inline_handlers -->|"queries tasks"| node_task_utils
node_inline_handlers -->|"checks answers"| node_task_service
node_inline_handlers -->|"loads achievements"| node_achievement_service
node_inline_handlers -->|"builds answer UI"| node_inline_keyboards
node_inline_handlers -->|"updates state"| node_fsm
node_task_service -->|"gets random task"| node_task_utils
node_task_service -->|"delegates checking"| node_answer_checker
node_answer_checker -->|"updates statistics"| node_stats_service
node_answer_checker -->|"checks achievements"| node_achievement_service
node_task_display -->|"builds task controls"| node_inline_keyboards
node_task_display -->|"builds navigation"| node_keyboards
node_admin_handlers -->|"restricts commands"| node_admin_filter
node_staff_handlers -->|"checks staff access"| node_admin_filter
node_admin_handlers -->|"manages statistics"| node_stats_service
node_admin_handlers -->|"manages achievements"| node_achievement_service
node_admin_handlers -->|"sends reminders"| node_reminder_service
node_reminder_scheduler -->|"schedules reminders"| node_reminder_service
node_reminder_jobs -->|"runs reminder job"| node_reminder_service
node_reminder_service -->|"sends messages"| node_telegram
node_database -.->|"provides persistence"| node_models
node_user_service -->|"manages user records"| node_models
node_stats_service -->|"reads and updates"| node_models
node_achievement_service -->|"reads and updates"| node_models
node_reminder_service -->|"reads reminder data"| node_models

click node_bot "https://github.com/itwistiks/physics_bot/blob/main/core/bot.py"
click node_reply_handlers "https://github.com/itwistiks/physics_bot/blob/main/core/handlers/reply_handlers.py"
click node_inline_handlers "https://github.com/itwistiks/physics_bot/blob/main/core/handlers/inline_handlers.py"
click node_keyboards "https://github.com/itwistiks/physics_bot/blob/main/core/keyboards/reply.py"
click node_inline_keyboards "https://github.com/itwistiks/physics_bot/blob/main/core/keyboards/inline.py"
click node_fsm "https://github.com/itwistiks/physics_bot/blob/main/core/fsm/states.py"
click node_task_display "https://github.com/itwistiks/physics_bot/blob/main/core/services/task_display.py"
click node_task_service "https://github.com/itwistiks/physics_bot/blob/main/core/services/task_service.py"
click node_task_utils "https://github.com/itwistiks/physics_bot/blob/main/core/services/task_utils.py"
click node_answer_checker "https://github.com/itwistiks/physics_bot/blob/main/core/services/answer_checker.py"
click node_answer_processing "https://github.com/itwistiks/physics_bot/blob/main/core/services/answer_processing.py"
click node_models "https://github.com/itwistiks/physics_bot/blob/main/core/database/models.py"
click node_database "https://github.com/itwistiks/physics_bot/blob/main/config/database.py"
click node_user_service "https://github.com/itwistiks/physics_bot/blob/main/core/services/user_service.py"
click node_stats_service "https://github.com/itwistiks/physics_bot/blob/main/core/services/stats_service.py"
click node_achievement_service "https://github.com/itwistiks/physics_bot/blob/main/core/services/achievement_service.py"
click node_admin_handlers "https://github.com/itwistiks/physics_bot/blob/main/core/handlers/admin.py"
click node_staff_handlers "https://github.com/itwistiks/physics_bot/blob/main/core/handlers/teacher.py"
click node_admin_filter "https://github.com/itwistiks/physics_bot/blob/main/core/filters/admin.py"
click node_reminder_service "https://github.com/itwistiks/physics_bot/blob/main/core/services/reminder_service.py"
click node_reminder_scheduler "https://github.com/itwistiks/physics_bot/blob/main/core/utils/reminder_scheduler.py"
click node_reminder_jobs "https://github.com/itwistiks/physics_bot/blob/main/core/utils/reminder_jobs.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,node_reply_handlers,node_inline_handlers,node_keyboards,node_inline_keyboards,node_fsm toneBlue
class node_task_display,node_task_service,node_task_utils,node_answer_checker,node_answer_processing toneAmber
class node_user_service,node_stats_service,node_achievement_service,node_telegram toneMint
class node_admin_handlers,node_staff_handlers,node_admin_filter,node_reminder_service,node_reminder_scheduler,node_reminder_jobs toneRose
class node_models,node_database,node_student toneIndigo
```

## Components

### Telegram interaction

- [Bot startup and routing](https://github.com/itwistiks/physics_bot/blob/main/core/bot.py): `core/bot.py`
- [Menu and practice handlers](https://github.com/itwistiks/physics_bot/blob/main/core/handlers/reply_handlers.py): `core/handlers/reply_handlers.py`
- [Task callback handlers](https://github.com/itwistiks/physics_bot/blob/main/core/handlers/inline_handlers.py): `core/handlers/inline_handlers.py`
- [Practice keyboards](https://github.com/itwistiks/physics_bot/blob/main/core/keyboards/reply.py): `core/keyboards/reply.py`
- [Answer keyboards](https://github.com/itwistiks/physics_bot/blob/main/core/keyboards/inline.py): `core/keyboards/inline.py`
- [Practice state](https://github.com/itwistiks/physics_bot/blob/main/core/fsm/states.py): `core/fsm/states.py`

### Practice and learning

- [Task presentation](https://github.com/itwistiks/physics_bot/blob/main/core/services/task_display.py): `core/services/task_display.py`
- [Task selection and checking](https://github.com/itwistiks/physics_bot/blob/main/core/services/task_service.py): `core/services/task_service.py`
- [Task query utilities](https://github.com/itwistiks/physics_bot/blob/main/core/services/task_utils.py): `core/services/task_utils.py`
- [Answer evaluation](https://github.com/itwistiks/physics_bot/blob/main/core/services/answer_checker.py): `core/services/answer_checker.py`
- [Answer processing](https://github.com/itwistiks/physics_bot/blob/main/core/services/answer_processing.py): `core/services/answer_processing.py`

### Progress and rewards

- [User records](https://github.com/itwistiks/physics_bot/blob/main/core/services/user_service.py): `core/services/user_service.py`
- [Progress and statistics](https://github.com/itwistiks/physics_bot/blob/main/core/services/stats_service.py): `core/services/stats_service.py`
- [Achievements and rewards](https://github.com/itwistiks/physics_bot/blob/main/core/services/achievement_service.py): `core/services/achievement_service.py`

### Administration and reminders

- [Admin controls](https://github.com/itwistiks/physics_bot/blob/main/core/handlers/admin.py): `core/handlers/admin.py`
- [Teacher and moderator controls](https://github.com/itwistiks/physics_bot/blob/main/core/handlers/teacher.py): `core/handlers/teacher.py`
- [Staff authorization](https://github.com/itwistiks/physics_bot/blob/main/core/filters/admin.py): `core/filters/admin.py`
- [Inactivity reminders](https://github.com/itwistiks/physics_bot/blob/main/core/services/reminder_service.py): `core/services/reminder_service.py`
- [Reminder scheduler](https://github.com/itwistiks/physics_bot/blob/main/core/utils/reminder_scheduler.py): `core/utils/reminder_scheduler.py`
- [Reminder jobs](https://github.com/itwistiks/physics_bot/blob/main/core/utils/reminder_jobs.py): `core/utils/reminder_jobs.py`

### Persistence

- [Learning and user models](https://github.com/itwistiks/physics_bot/blob/main/core/database/models.py): `core/database/models.py`
- [MySQL session and engine](https://github.com/itwistiks/physics_bot/blob/main/config/database.py): `config/database.py`

### Other components

- **Student**
- **Telegram Bot API**

## Connections

- Student → Telegram Bot API: sends requests (evidence: `README.md`)
- Bot startup and routing → Telegram Bot API: serves updates (evidence: `README.md`)
- Bot startup and routing → Menu and practice handlers: registers routes (evidence: `core/bot.py`)
- Bot startup and routing → Task callback handlers: registers routes (evidence: `core/bot.py`)
- Bot startup and routing → Reminder scheduler: starts scheduler (evidence: `core/bot.py`)
- Menu and practice handlers → Practice keyboards: presents menus (evidence: `core/handlers/reply_handlers.py`)
- Menu and practice handlers → Task presentation: displays tasks (evidence: `core/handlers/reply_handlers.py`)
- Menu and practice handlers → Task query utilities: queries tasks (evidence: `core/handlers/reply_handlers.py`)
- Menu and practice handlers → Task selection and checking: uses task service (evidence: `core/handlers/reply_handlers.py`)
- Menu and practice handlers → Progress and statistics: loads statistics (evidence: `core/handlers/reply_handlers.py`)
- Task callback handlers → Task presentation: displays tasks (evidence: `core/handlers/inline_handlers.py`)
- Task callback handlers → Task query utilities: queries tasks (evidence: `core/handlers/inline_handlers.py`)
- Task callback handlers → Task selection and checking: checks answers (evidence: `core/handlers/inline_handlers.py`)
- Task callback handlers → Achievements and rewards: loads achievements (evidence: `core/handlers/inline_handlers.py`)
- Task callback handlers → Answer keyboards: builds answer UI (evidence: `core/handlers/inline_handlers.py`)
- Task callback handlers → Practice state: updates state (evidence: `core/handlers/inline_handlers.py`)
- Task selection and checking → Task query utilities: gets random task (evidence: `core/services/task_service.py`)
- Task selection and checking → Answer evaluation: delegates checking (evidence: `core/services/task_service.py`)
- Answer evaluation → Progress and statistics: updates statistics (evidence: `core/services/answer_checker.py`)
- Answer evaluation → Achievements and rewards: checks achievements (evidence: `core/services/answer_checker.py`)
- Task presentation → Answer keyboards: builds task controls (evidence: `core/services/task_display.py`)
- Task presentation → Practice keyboards: builds navigation (evidence: `core/services/task_display.py`)
- Admin controls → Staff authorization: restricts commands (evidence: `core/handlers/admin.py`)
- Teacher and moderator controls → Staff authorization: checks staff access (evidence: `core/handlers/teacher.py`)
- Admin controls → Progress and statistics: manages statistics (evidence: `core/handlers/admin.py`)
- Admin controls → Achievements and rewards: manages achievements (evidence: `core/handlers/admin.py`)
- Admin controls → Inactivity reminders: sends reminders (evidence: `core/handlers/admin.py`)
- Reminder scheduler → Inactivity reminders: schedules reminders (evidence: `core/utils/reminder_scheduler.py`)
- Reminder jobs → Inactivity reminders: runs reminder job (evidence: `core/utils/reminder_jobs.py`)
- Inactivity reminders → Telegram Bot API: sends messages (evidence: `core/services/reminder_service.py`)
- MySQL session and engine → Learning and user models: provides persistence
- User records → Learning and user models: manages user records (evidence: `core/services/user_service.py`)
- Progress and statistics → Learning and user models: reads and updates (evidence: `core/services/stats_service.py`)
- Achievements and rewards → Learning and user models: reads and updates (evidence: `core/services/achievement_service.py`)
- Inactivity reminders → Learning and user models: reads reminder data (evidence: `core/services/reminder_service.py`)
