# abdkrn/pp_statistics architecture

> Architecture diagram of the GitHub repository abdkrn/pp_statistics, 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/abdkrn/pp_statistics
- Repository: https://github.com/abdkrn/pp_statistics

## Overview

PP Statistics Bot tracks manager assignments made explicitly by administrators in one Telegram work chat. Its main workflow filters incoming messages by chat and administrator, parses an assignment, resolves the manager, and saves a deduplicated record; commands then calculate and present monthly, all-time, and per-month statistics. Separate branches handle manager administration, manual statistical corrections, and idempotent historical-chat import. The README documents backups and JSON storage; excerpts show storage and backup setup, but do not expose all backup internals or every command implementation detail.

Main entry points: [`services/storage.py`](https://github.com/abdkrn/pp_statistics/blob/main/services/storage.py) (JSON storage and backups), [`bot.py`](https://github.com/abdkrn/pp_statistics/blob/main/bot.py) (Bot startup and routing), [`handlers/messages.py`](https://github.com/abdkrn/pp_statistics/blob/main/handlers/messages.py) (Assignment message handler), [`handlers/commands.py`](https://github.com/abdkrn/pp_statistics/blob/main/handlers/commands.py) (Commands and statistics views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_bot["Bot startup and routing<br/>[bot.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_assignment["Assignment tracking"]
  node_message_handler["Assignment message handler<br/>[messages.py]"]
  node_parser["Assignment parser"]
  node_history_import["History importer<br/>[import_history.py]"]
end

subgraph group_management["Manager administration"]
  node_admin_handler["Admin commands<br/>[admin.py]"]
  node_manager_service["Manager operations<br/>[managers.py]"]
end

subgraph group_reporting["Statistics and history"]
  node_command_handler["Commands and statistics views<br/>[commands.py]"]
  node_statistics["Statistics calculations<br/>[statistics.py]"]
  node_statistics_keyboard["Statistics navigation<br/>[statistics.py]"]
end

subgraph group_persistence["Persistence"]
  node_storage["JSON storage and backups<br/>[storage.py]"]
  node_json_files[("Managers, assignments, corrections, settings")]
end

node_admin(("Administrator"))
node_manager(("Manager"))
node_telegram["Telegram"]
node_import_export["Telegram history export"]

node_admin -->|"sends commands"| node_telegram
node_manager -->|"sends messages"| node_telegram
node_telegram -->|"delivers updates"| node_bot
node_bot -->|"loads settings"| node_config
node_bot -->|"routes updates"| node_message_handler
node_bot -->|"registers router"| node_admin_handler
node_bot -->|"registers router"| node_command_handler
node_bot -->|"initializes and backs up"| node_storage
node_message_handler -->|"checks chat and admin"| node_config
node_message_handler -->|"parses assignment text"| node_parser
node_message_handler -->|"resolves manager"| node_manager_service
node_message_handler -->|"saves assignment"| node_storage
node_admin_handler -->|"manages managers"| node_manager_service
node_admin_handler -->|"saves corrections"| node_storage
node_manager_service -->|"reads and updates"| node_storage
node_command_handler -->|"loads records"| node_storage
node_command_handler -->|"calculates views"| node_statistics
node_command_handler -->|"builds navigation"| node_statistics_keyboard
node_storage -->|"reads and writes"| node_json_files
node_history_import -->|"reads export"| node_import_export
node_history_import -->|"parses exported messages"| node_parser
node_history_import -->|"bulk saves assignments"| node_storage
node_history_import -->|"uses statistics service"| node_statistics
node_admin -->|"runs admin commands"| node_admin_handler
node_manager -->|"requests statistics"| node_command_handler

click node_bot "https://github.com/abdkrn/pp_statistics/blob/main/bot.py"
click node_config "https://github.com/abdkrn/pp_statistics/blob/main/config.py"
click node_message_handler "https://github.com/abdkrn/pp_statistics/blob/main/handlers/messages.py"
click node_parser "https://github.com/abdkrn/pp_statistics/blob/main/services/assignment_parser.py"
click node_history_import "https://github.com/abdkrn/pp_statistics/blob/main/import_history.py"
click node_admin_handler "https://github.com/abdkrn/pp_statistics/blob/main/handlers/admin.py"
click node_manager_service "https://github.com/abdkrn/pp_statistics/blob/main/services/managers.py"
click node_command_handler "https://github.com/abdkrn/pp_statistics/blob/main/handlers/commands.py"
click node_statistics "https://github.com/abdkrn/pp_statistics/blob/main/services/statistics.py"
click node_statistics_keyboard "https://github.com/abdkrn/pp_statistics/blob/main/keyboards/statistics.py"
click node_storage "https://github.com/abdkrn/pp_statistics/blob/main/services/storage.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_config toneBlue
class node_message_handler,node_parser,node_history_import toneAmber
class node_admin_handler,node_manager_service toneMint
class node_command_handler,node_statistics,node_statistics_keyboard toneRose
class node_storage,node_json_files,node_admin,node_manager,node_telegram,node_import_export toneIndigo
```

## Components

### Bot runtime

- [Bot startup and routing](https://github.com/abdkrn/pp_statistics/blob/main/bot.py): `bot.py`
- [Configuration](https://github.com/abdkrn/pp_statistics/blob/main/config.py): `config.py`

### Assignment tracking

- [Assignment message handler](https://github.com/abdkrn/pp_statistics/blob/main/handlers/messages.py): `handlers/messages.py`
- [Assignment parser](https://github.com/abdkrn/pp_statistics/blob/main/services/assignment_parser.py): `services/assignment_parser.py`
- [History importer](https://github.com/abdkrn/pp_statistics/blob/main/import_history.py): `import_history.py`

### Manager administration

- [Admin commands](https://github.com/abdkrn/pp_statistics/blob/main/handlers/admin.py): `handlers/admin.py`
- [Manager operations](https://github.com/abdkrn/pp_statistics/blob/main/services/managers.py): `services/managers.py`

### Statistics and history

- [Commands and statistics views](https://github.com/abdkrn/pp_statistics/blob/main/handlers/commands.py): `handlers/commands.py`
- [Statistics calculations](https://github.com/abdkrn/pp_statistics/blob/main/services/statistics.py): `services/statistics.py`
- [Statistics navigation](https://github.com/abdkrn/pp_statistics/blob/main/keyboards/statistics.py): `keyboards/statistics.py`

### Persistence

- [JSON storage and backups](https://github.com/abdkrn/pp_statistics/blob/main/services/storage.py): `services/storage.py`
- **Managers, assignments, corrections, settings**

### Other components

- **Administrator**
- **Manager**
- **Telegram**
- **Telegram history export**

## Connections

- Administrator → Telegram: sends commands (evidence: `README.md`)
- Manager → Telegram: sends messages (evidence: `README.md`)
- Telegram → Bot startup and routing: delivers updates (evidence: `bot.py`)
- Bot startup and routing → Configuration: loads settings (evidence: `bot.py`)
- Bot startup and routing → Assignment message handler: routes updates (evidence: `bot.py`)
- Bot startup and routing → Admin commands: registers router (evidence: `bot.py`)
- Bot startup and routing → Commands and statistics views: registers router (evidence: `bot.py`)
- Bot startup and routing → JSON storage and backups: initializes and backs up (evidence: `bot.py`)
- Assignment message handler → Configuration: checks chat and admin (evidence: `handlers/messages.py`)
- Assignment message handler → Assignment parser: parses assignment text (evidence: `handlers/messages.py`)
- Assignment message handler → Manager operations: resolves manager (evidence: `handlers/messages.py`)
- Assignment message handler → JSON storage and backups: saves assignment (evidence: `handlers/messages.py`)
- Admin commands → Manager operations: manages managers (evidence: `handlers/admin.py`)
- Admin commands → JSON storage and backups: saves corrections (evidence: `handlers/admin.py`)
- Manager operations → JSON storage and backups: reads and updates (evidence: `services/managers.py`)
- Commands and statistics views → JSON storage and backups: loads records (evidence: `handlers/commands.py`)
- Commands and statistics views → Statistics calculations: calculates views (evidence: `handlers/commands.py`)
- Commands and statistics views → Statistics navigation: builds navigation (evidence: `handlers/commands.py`)
- JSON storage and backups → Managers, assignments, corrections, settings: reads and writes (evidence: `services/storage.py`)
- History importer → Telegram history export: reads export (evidence: `README.md`)
- History importer → Assignment parser: parses exported messages (evidence: `import_history.py`)
- History importer → JSON storage and backups: bulk saves assignments (evidence: `import_history.py`)
- History importer → Statistics calculations: uses statistics service (evidence: `import_history.py`)
- Administrator → Admin commands: runs admin commands (evidence: `README.md`)
- Manager → Commands and statistics views: requests statistics (evidence: `README.md`)
