# sophannlearning-wq/tpmtelev2 architecture

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

- Interactive diagram: https://gitdiagram.com/sophannlearning-wq/tpmtelev2
- Repository: https://github.com/sophannlearning-wq/tpmtelev2

## Overview

TPM Master Training Bot manages role-based training workflows through Telegram: users submit requests or Excel files, the bot routes them to training operations, and results are stored or returned as messages and workbooks. The main entry point also loads configuration, initializes the database, imports bootstrap data, and schedules reminders. The graph separates interaction, training operations, and persistence. README capabilities are represented where source excerpts are incomplete; links among unsampled handler details are limited to the registrations shown in app/main.py.

Main entry points: [`app/main.py`](https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/main.py) (Bot entry and routing), [`app/database/db.py`](https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/database/db.py) (Database sessions), [`app/services/training.py`](https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/services/training.py) (Plan and status logic), [`app/services/reminders.py`](https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/services/reminders.py) (Reminder service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Telegram interaction"]
  node_entry["Bot entry and routing<br/>[main.py]"]
  node_menus["Role menus<br/>[menus.py]"]
end

subgraph group_operations["Training operations"]
  node_identity["Linking and profiles<br/>[core.py]"]
  node_training_views["Dashboards and plans<br/>[core.py]"]
  node_scores["Score updates<br/>[core.py]"]
  node_schedules["Schedule management<br/>[core.py]"]
  node_attendance["Attendance uploads<br/>[core.py]"]
  node_followup["Follow-up training<br/>[core.py]"]
  node_reports["Training reports<br/>[reports.py]"]
  node_reminders["Reminder service<br/>[reminders.py]"]
  node_training_logic["Plan and status logic<br/>[training.py]"]
end

subgraph group_persistence["Data and persistence"]
  node_importer["Excel bootstrap import<br/>[importer.py]"]
  node_db_access["Database sessions<br/>[db.py]"]
  node_schema[("Training records<br/>[models.py]")]
end

subgraph group_runtime["Runtime setup"]
  node_settings["Runtime settings<br/>[config.py]"]
end

node_users(("Admin, staff, supervisors"))
node_telegram["Telegram"]

node_users -->|"send requests"| node_telegram
node_telegram -->|"deliver updates"| node_entry
node_entry -->|"poll updates"| node_telegram
node_entry -->|"loads settings"| node_settings
node_entry -->|"configures database"| node_db_access
node_db_access -->|"creates tables"| node_schema
node_entry -->|"imports bootstrap data"| node_importer
node_entry -->|"routes conversations"| node_identity
node_entry -->|"routes views"| node_training_views
node_entry -->|"routes uploads"| node_scores
node_entry -->|"routes scheduling"| node_schedules
node_entry -->|"routes uploads"| node_attendance
node_entry -->|"routes follow-up"| node_followup
node_entry -->|"routes reports"| node_reports
node_entry -->|"schedules reminder job"| node_reminders
node_entry -.->|"uses menus"| node_menus
node_identity -->|"queries records"| node_db_access
node_training_views -->|"calculates plans"| node_training_logic
node_scores -.->|"stores scores"| node_db_access
node_schedules -.->|"updates schedules"| node_db_access
node_attendance -.->|"stores attendance"| node_db_access
node_followup -.->|"creates workbooks"| node_reports
node_reports -->|"uses plan status"| node_training_logic
node_reminders -->|"checks training status"| node_training_logic
node_reminders -->|"reads and records"| node_db_access
node_importer -->|"imports records"| node_db_access
node_training_logic -->|"reads training records"| node_schema
node_menus -.->|"presents options"| node_users

click node_entry "https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/main.py"
click node_menus "https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/keyboards/menus.py"
click node_identity "https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/handlers/core.py"
click node_training_views "https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/handlers/core.py"
click node_scores "https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/handlers/core.py"
click node_schedules "https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/handlers/core.py"
click node_attendance "https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/handlers/core.py"
click node_followup "https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/handlers/core.py"
click node_reports "https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/services/reports.py"
click node_reminders "https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/services/reminders.py"
click node_training_logic "https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/services/training.py"
click node_importer "https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/services/importer.py"
click node_db_access "https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/database/db.py"
click node_schema "https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/database/models.py"
click node_settings "https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/config.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_entry,node_menus toneBlue
class node_identity,node_training_views,node_scores,node_schedules,node_attendance,node_followup,node_reports,node_reminders,node_training_logic toneAmber
class node_importer,node_db_access,node_schema toneMint
class node_settings toneRose
class node_users,node_telegram toneIndigo
```

## Components

### Telegram interaction

- [Bot entry and routing](https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/main.py): `app/main.py`
- [Role menus](https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/keyboards/menus.py): `app/keyboards/menus.py`

### Training operations

- [Linking and profiles](https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/handlers/core.py): `app/handlers/core.py`
- [Dashboards and plans](https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/handlers/core.py): `app/handlers/core.py`
- [Score updates](https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/handlers/core.py): `app/handlers/core.py`
- [Schedule management](https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/handlers/core.py): `app/handlers/core.py`
- [Attendance uploads](https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/handlers/core.py): `app/handlers/core.py`
- [Follow-up training](https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/handlers/core.py): `app/handlers/core.py`
- [Training reports](https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/services/reports.py): `app/services/reports.py`
- [Reminder service](https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/services/reminders.py): `app/services/reminders.py`
- [Plan and status logic](https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/services/training.py): `app/services/training.py`

### Data and persistence

- [Excel bootstrap import](https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/services/importer.py): `app/services/importer.py`
- [Database sessions](https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/database/db.py): `app/database/db.py`
- [Training records](https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/database/models.py): `app/database/models.py`

### Runtime setup

- [Runtime settings](https://github.com/sophannlearning-wq/tpmtelev2/blob/main/app/config.py): `app/config.py`

### Other components

- **Admin, staff, supervisors**
- **Telegram**

## Connections

- Admin, staff, supervisors → Telegram: send requests (evidence: `README.md`)
- Telegram → Bot entry and routing: deliver updates (evidence: `app/main.py`)
- Bot entry and routing → Telegram: poll updates (evidence: `app/main.py`)
- Bot entry and routing → Runtime settings: loads settings (evidence: `app/main.py`)
- Bot entry and routing → Database sessions: configures database (evidence: `app/main.py`)
- Database sessions → Training records: creates tables (evidence: `app/database/db.py`)
- Bot entry and routing → Excel bootstrap import: imports bootstrap data (evidence: `app/main.py`)
- Bot entry and routing → Linking and profiles: routes conversations (evidence: `app/main.py`)
- Bot entry and routing → Dashboards and plans: routes views (evidence: `app/main.py`)
- Bot entry and routing → Score updates: routes uploads (evidence: `app/main.py`)
- Bot entry and routing → Schedule management: routes scheduling (evidence: `app/main.py`)
- Bot entry and routing → Attendance uploads: routes uploads (evidence: `app/main.py`)
- Bot entry and routing → Follow-up training: routes follow-up (evidence: `app/main.py`)
- Bot entry and routing → Training reports: routes reports (evidence: `app/main.py`)
- Bot entry and routing → Reminder service: schedules reminder job (evidence: `app/main.py`)
- Bot entry and routing → Role menus: uses menus
- Linking and profiles → Database sessions: queries records (evidence: `app/handlers/core.py`)
- Dashboards and plans → Plan and status logic: calculates plans (evidence: `app/handlers/core.py`)
- Score updates → Database sessions: stores scores (evidence: `app/handlers/core.py`)
- Schedule management → Database sessions: updates schedules (evidence: `app/handlers/core.py`)
- Attendance uploads → Database sessions: stores attendance (evidence: `app/handlers/core.py`)
- Follow-up training → Training reports: creates workbooks (evidence: `app/handlers/core.py`)
- Training reports → Plan and status logic: uses plan status (evidence: `app/services/reports.py`)
- Reminder service → Plan and status logic: checks training status (evidence: `app/services/reminders.py`)
- Reminder service → Database sessions: reads and records (evidence: `app/services/reminders.py`)
- Excel bootstrap import → Database sessions: imports records (evidence: `app/services/importer.py`)
- Plan and status logic → Training records: reads training records (evidence: `app/services/training.py`)
- Role menus → Admin, staff, supervisors: presents options
