# kimheng-sok/telegram_bots architecture

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

## Overview

This is a bilingual Telegram bot for creating football matches, collecting availability, and managing match announcements in group chats. The main workflow is: a group user submits `/newmatch`, the wizard parses and previews the form, saves the match, and posts a pinned card; users then vote through commands or inline buttons, updating the card. Administrators can close or reopen voting, while group-language settings and help are separate capabilities. `utils.py` provides parsing, rendering, and Telegram-message helpers. The excerpts show handler registration and database operations; external database configuration supports multiple engines, but deployment-specific wiring is not mapped.

Main entry points: [`main.py`](https://github.com/kimheng-sok/telegram_bots/blob/main/main.py) (Bot entrypoint), [`database.py`](https://github.com/kimheng-sok/telegram_bots/blob/main/database.py) (Match and vote data), [`handlers/match_wizard.py`](https://github.com/kimheng-sok/telegram_bots/blob/main/handlers/match_wizard.py) (Match wizard), [`handlers/voting.py`](https://github.com/kimheng-sok/telegram_bots/blob/main/handlers/voting.py) (Voting and controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_entry["Bot entrypoint<br/>[main.py]"]
end

subgraph group_workflows["Group workflows"]
  node_wizard["Match wizard<br/>[match_wizard.py]"]
  node_voting["Voting and controls<br/>[voting.py]"]
  node_general["Help and language<br/>[general.py]"]
end

subgraph group_presentation["Language and presentation"]
  node_helpers["Form and card helpers<br/>[utils.py]"]
  node_translations["English and Khmer<br/>[strings.py]"]
end

subgraph group_persistence["Configuration and data"]
  node_settings["Bot configuration<br/>[config.py]"]
  node_database[("Match and vote data<br/>[database.py]")]
end

node_group_users(("Group users"))
node_telegram["Telegram API"]

node_group_users -->|"send updates"| node_telegram
node_telegram -->|"poll updates"| node_entry
node_entry -->|"loads token"| node_settings
node_entry -->|"initializes"| node_database
node_entry -->|"registers wizard"| node_wizard
node_entry -->|"registers commands"| node_voting
node_entry -->|"registers commands"| node_general
node_wizard -->|"parses and renders"| node_helpers
node_wizard -->|"creates match"| node_database
node_wizard -->|"formats prompts"| node_translations
node_wizard -->|"posts and pins"| node_telegram
node_voting -->|"records votes"| node_database
node_voting -->|"refreshes card"| node_helpers
node_voting -->|"formats replies"| node_translations
node_voting -->|"updates match card"| node_telegram
node_general -->|"reads and sets language"| node_database
node_general -->|"checks and cleans"| node_helpers
node_general -->|"formats replies"| node_translations
node_general -->|"sends menus"| node_telegram
node_helpers -->|"loads match and votes"| node_database
node_helpers -->|"renders labels"| node_translations
node_database -->|"reads database settings"| node_settings

click node_entry "https://github.com/kimheng-sok/telegram_bots/blob/main/main.py"
click node_wizard "https://github.com/kimheng-sok/telegram_bots/blob/main/handlers/match_wizard.py"
click node_voting "https://github.com/kimheng-sok/telegram_bots/blob/main/handlers/voting.py"
click node_general "https://github.com/kimheng-sok/telegram_bots/blob/main/handlers/general.py"
click node_helpers "https://github.com/kimheng-sok/telegram_bots/blob/main/utils.py"
click node_translations "https://github.com/kimheng-sok/telegram_bots/blob/main/strings.py"
click node_settings "https://github.com/kimheng-sok/telegram_bots/blob/main/config.py"
click node_database "https://github.com/kimheng-sok/telegram_bots/blob/main/database.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_group_users toneBlue
class node_wizard,node_voting,node_general toneAmber
class node_helpers,node_translations,node_telegram toneMint
class node_settings,node_database toneRose
```

## Components

### Bot runtime

- [Bot entrypoint](https://github.com/kimheng-sok/telegram_bots/blob/main/main.py): `main.py`

### Group workflows

- [Match wizard](https://github.com/kimheng-sok/telegram_bots/blob/main/handlers/match_wizard.py): `handlers/match_wizard.py`
- [Voting and controls](https://github.com/kimheng-sok/telegram_bots/blob/main/handlers/voting.py): `handlers/voting.py`
- [Help and language](https://github.com/kimheng-sok/telegram_bots/blob/main/handlers/general.py): `handlers/general.py`

### Language and presentation

- [Form and card helpers](https://github.com/kimheng-sok/telegram_bots/blob/main/utils.py): `utils.py`
- [English and Khmer](https://github.com/kimheng-sok/telegram_bots/blob/main/strings.py): `strings.py`

### Configuration and data

- [Bot configuration](https://github.com/kimheng-sok/telegram_bots/blob/main/config.py): `config.py`
- [Match and vote data](https://github.com/kimheng-sok/telegram_bots/blob/main/database.py): `database.py`

### Other components

- **Group users**
- **Telegram API**

## Connections

- Group users → Telegram API: send updates (evidence: `README.md`)
- Telegram API → Bot entrypoint: poll updates (evidence: `main.py`)
- Bot entrypoint → Bot configuration: loads token (evidence: `main.py`)
- Bot entrypoint → Match and vote data: initializes (evidence: `main.py`)
- Bot entrypoint → Match wizard: registers wizard (evidence: `main.py`)
- Bot entrypoint → Voting and controls: registers commands (evidence: `main.py`)
- Bot entrypoint → Help and language: registers commands (evidence: `main.py`)
- Match wizard → Form and card helpers: parses and renders (evidence: `handlers/match_wizard.py`)
- Match wizard → Match and vote data: creates match (evidence: `handlers/match_wizard.py`)
- Match wizard → English and Khmer: formats prompts (evidence: `handlers/match_wizard.py`)
- Match wizard → Telegram API: posts and pins (evidence: `handlers/match_wizard.py`)
- Voting and controls → Match and vote data: records votes (evidence: `handlers/voting.py`)
- Voting and controls → Form and card helpers: refreshes card (evidence: `handlers/voting.py`)
- Voting and controls → English and Khmer: formats replies (evidence: `handlers/voting.py`)
- Voting and controls → Telegram API: updates match card (evidence: `handlers/voting.py`)
- Help and language → Match and vote data: reads and sets language (evidence: `handlers/general.py`)
- Help and language → Form and card helpers: checks and cleans (evidence: `handlers/general.py`)
- Help and language → English and Khmer: formats replies (evidence: `handlers/general.py`)
- Help and language → Telegram API: sends menus (evidence: `handlers/general.py`)
- Form and card helpers → Match and vote data: loads match and votes (evidence: `utils.py`)
- Form and card helpers → English and Khmer: renders labels (evidence: `utils.py`)
- Match and vote data → Bot configuration: reads database settings (evidence: `database.py`)
