# pastking/tgbot-verify architecture

> Architecture diagram of the GitHub repository pastking/tgbot-verify, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pastking/tgbot-verify
- Repository: https://github.com/pastking/tgbot-verify

## Overview

#### Purpose and Entry Point
This is a Python Telegram bot that automates SheerID student/teacher verification submissions for several partner programs. Runtime starts at `bot.py`, which loads global settings from `config.py`, connects to MySQL through `database_mysql.py`, and registers command handlers.

#### Telegram Command Layer
User, administrator, and verification commands are separated by responsibility:
- `handlers/user_commands.py` manages registration, balance, check-in, invitations, and redemption.
- `handlers/admin_commands.py` manages balances, blocklists, keys, and broadcasts.
- `handlers/verify_commands.py` accepts verification URLs, applies eligibility/credit checks, selects a program workflow, and reports results to Telegram.

#### Credits, Access, and Persistence
MySQL is the durable boundary for user records, balances, check-in state, invitations, redemption keys, and blacklist/admin operations. `database_mysql.py` centralizes persistence; global reward and verification-cost policy is in `config.py`. Request admission and likely channel/access checks are shared utilities in `utils/checks.py` and `utils/concurrency.py`.

#### Verification Workflow
Each `/verify*` command receives a SheerID URL containing a `verificationId`. The selected service module generates identity data, creates a supporting document image, and submits the verification flow to SheerID. The external boundary is SheerID’s REST/API and browser-driven verification process, using `httpx` and Playwright.

#### Program-Specific Adapters
Programs are isolated into parallel packages, each with its own active SheerID `programId` configuration, identity generation, document rendering, and verifier implementation:
- Gemini One: `one/config.py`, `one/name_generator.py`, `one/sheerid_verifier.py`
- ChatGPT K12: `k12/config.py`, `k12/img_generator.py`, `k12/sheerid_verifier.py`
- Spotify: `spotify/config.py`, `spotify/img_generator.py`, `spotify/sheerid_verifier.py`
- Bolt.new: `Boltnew/config.py`, `Boltnew/img_generator.py`, `Boltnew/sheerid_verifier.py`
- YouTube: `youtube/config.py`, `youtube/img_generator.py`, `youtube/sheerid_verifier.py`

This package boundary allows program IDs and provider-specific payload/document behavior to change independently.

#### Document and Identity Generation
Each provider adapter contains its own synthetic name and credential-image generation implementation. Images are produced as PNG evidence for the downstream SheerID submission; the K12 template is represented by `k12/card-temp.html`. Python imaging/PDF dependencies include Pillow, reportlab, and xhtml2pdf.

#### Runtime and Deployment
The bot requires Python 3.11+, `python-telegram-bot`, MySQL 5.7+, Playwright Chromium, and environment-supplied Telegram/MySQL credentials. Container deployment is defined by `Dockerfile` and `docker-compose.yml`; expected environment inputs are documented in `env.example`. External services are Telegram, MySQL, SheerID, and the supported partner verification programs.

Main entry points: [`handlers/verify_commands.py`](https://github.com/pastking/tgbot-verify/blob/main/handlers/verify_commands.py) (Verification commands), [`bot.py`](https://github.com/pastking/tgbot-verify/blob/main/bot.py) (Bot entry point), [`database_mysql.py`](https://github.com/pastking/tgbot-verify/blob/main/database_mysql.py) (MySQL persistence), [`one/sheerid_verifier.py`](https://github.com/pastking/tgbot-verify/blob/main/one/sheerid_verifier.py) (Gemini One)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot Runtime"]
  node_bot["Bot entry point<br/>Python runtime<br/>[bot.py]"]
  node_config["Global policy<br/>settings<br/>[config.py]"]
  node_database[("MySQL persistence<br/>database access<br/>[database_mysql.py]")]
  node_telegram(("Telegram<br/>external API"))
  node_deployment["Container deployment"]
end

subgraph group_commands["Telegram Commands"]
  node_user_commands["User commands<br/>command handlers<br/>[user_commands.py]"]
  node_admin_commands["Admin commands<br/>command handlers<br/>[admin_commands.py]"]
  node_verify_commands["Verification commands<br/>command handlers<br/>[verify_commands.py]"]
end

subgraph group_verification["Verification Pipeline"]
  node_access_checks["Access controls<br/>shared utilities<br/>[checks.py]"]
  node_concurrency["Concurrency controls<br/>shared utilities<br/>[concurrency.py]"]
  node_evidence["PNG evidence<br/>generated document"]
  node_sheerid(("SheerID<br/>external verification API"))
  node_partner_programs(("Partner programs<br/>external services"))
end

subgraph group_adapters["Program Adapters"]
  node_gemini_one{{"Gemini One<br/>program adapter"}}
  node_chatgpt_k12{{"ChatGPT K12<br/>program adapter"}}
  node_spotify{{"Spotify<br/>program adapter"}}
  node_boltnew{{"Bolt.new<br/>program adapter"}}
  node_youtube{{"YouTube<br/>program adapter"}}
end

node_telegram -->|"updates"| node_bot
node_bot -->|"loads"| node_config
node_bot -->|"connects"| node_database
node_bot -->|"registers"| node_user_commands
node_bot -->|"registers"| node_admin_commands
node_bot -->|"registers"| node_verify_commands
node_user_commands -->|"reads/writes accounts"| node_database
node_admin_commands -->|"admin operations"| node_database
node_verify_commands -->|"checks credits"| node_database
node_verify_commands -->|"uses verification cost"| node_config
node_verify_commands -->|"admission checks"| node_access_checks
node_verify_commands -->|"limits work"| node_concurrency
node_verify_commands -->|"selects workflow"| node_gemini_one
node_verify_commands -->|"selects workflow"| node_chatgpt_k12
node_verify_commands -->|"selects workflow"| node_spotify
node_verify_commands -->|"selects workflow"| node_boltnew
node_verify_commands -->|"selects workflow"| node_youtube
node_gemini_one -->|"generates"| node_evidence
node_chatgpt_k12 -->|"generates"| node_evidence
node_spotify -->|"generates"| node_evidence
node_boltnew -->|"generates"| node_evidence
node_youtube -->|"generates"| node_evidence
node_evidence -->|"submitted with identity"| node_sheerid
node_gemini_one -->|"API/browser flow"| node_sheerid
node_chatgpt_k12 -->|"API/browser flow"| node_sheerid
node_spotify -->|"API/browser flow"| node_sheerid
node_boltnew -->|"API/browser flow"| node_sheerid
node_youtube -->|"API/browser flow"| node_sheerid
node_sheerid -->|"verification programs"| node_partner_programs
node_deployment -->|"runs"| node_bot

click node_bot "https://github.com/pastking/tgbot-verify/blob/main/bot.py"
click node_config "https://github.com/pastking/tgbot-verify/blob/main/config.py"
click node_database "https://github.com/pastking/tgbot-verify/blob/main/database_mysql.py"
click node_user_commands "https://github.com/pastking/tgbot-verify/blob/main/handlers/user_commands.py"
click node_admin_commands "https://github.com/pastking/tgbot-verify/blob/main/handlers/admin_commands.py"
click node_verify_commands "https://github.com/pastking/tgbot-verify/blob/main/handlers/verify_commands.py"
click node_access_checks "https://github.com/pastking/tgbot-verify/blob/main/utils/checks.py"
click node_concurrency "https://github.com/pastking/tgbot-verify/blob/main/utils/concurrency.py"
click node_gemini_one "https://github.com/pastking/tgbot-verify/blob/main/one/sheerid_verifier.py"
click node_chatgpt_k12 "https://github.com/pastking/tgbot-verify/blob/main/k12/sheerid_verifier.py"
click node_spotify "https://github.com/pastking/tgbot-verify/blob/main/spotify/sheerid_verifier.py"
click node_boltnew "https://github.com/pastking/tgbot-verify/blob/main/Boltnew/sheerid_verifier.py"
click node_youtube "https://github.com/pastking/tgbot-verify/blob/main/youtube/sheerid_verifier.py"
click node_deployment "https://github.com/pastking/tgbot-verify/blob/main/Dockerfile"

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,node_database,node_telegram,node_deployment toneBlue
class node_user_commands,node_admin_commands,node_verify_commands toneAmber
class node_access_checks,node_concurrency,node_evidence,node_sheerid,node_partner_programs toneMint
class node_gemini_one,node_chatgpt_k12,node_spotify,node_boltnew,node_youtube toneRose
```

## Components

### Bot Runtime

- [Bot entry point](https://github.com/pastking/tgbot-verify/blob/main/bot.py): Python runtime · Loads settings, connects storage, and registers handlers. · `bot.py`
- [Global policy](https://github.com/pastking/tgbot-verify/blob/main/config.py): settings · Defines reward and verification-cost policy. · `config.py`
- [MySQL persistence](https://github.com/pastking/tgbot-verify/blob/main/database_mysql.py): database access · Centralizes users, balances, keys, invitations, and blocklists. · `database_mysql.py`
- **Telegram**: external API
- [Container deployment](https://github.com/pastking/tgbot-verify/blob/main/Dockerfile): deployment · Runs Python bot with Playwright Chromium and environment credentials. · `Dockerfile`

### Telegram Commands

- [User commands](https://github.com/pastking/tgbot-verify/blob/main/handlers/user_commands.py): command handlers · Registration, balances, check-in, invitations, and redemption. · `handlers/user_commands.py`
- [Admin commands](https://github.com/pastking/tgbot-verify/blob/main/handlers/admin_commands.py): command handlers · Balance, blocklist, key, and broadcast administration. · `handlers/admin_commands.py`
- [Verification commands](https://github.com/pastking/tgbot-verify/blob/main/handlers/verify_commands.py): command handlers · Admits requests, selects workflows, and reports outcomes. · `handlers/verify_commands.py`

### Verification Pipeline

- [Access controls](https://github.com/pastking/tgbot-verify/blob/main/utils/checks.py): shared utilities · Shared admission, channel/access, and concurrency checks. · `utils/checks.py`
- [Concurrency controls](https://github.com/pastking/tgbot-verify/blob/main/utils/concurrency.py): shared utilities · `utils/concurrency.py`
- **PNG evidence**: generated document · Synthetic identity and credential images submitted downstream.
- **SheerID**: external verification API · REST and browser-driven verification boundary.
- **Partner programs**: external services

### Program Adapters

Independent partner-specific verification workflows.

- [Gemini One](https://github.com/pastking/tgbot-verify/blob/main/one/sheerid_verifier.py): program adapter · Program configuration, identity generation, and verifier. · `one/sheerid_verifier.py`
- [ChatGPT K12](https://github.com/pastking/tgbot-verify/blob/main/k12/sheerid_verifier.py): program adapter · Generates credential-image evidence from its K12 template. · `k12/sheerid_verifier.py`
- [Spotify](https://github.com/pastking/tgbot-verify/blob/main/spotify/sheerid_verifier.py): program adapter · Program-specific identity, document, and verifier flow. · `spotify/sheerid_verifier.py`
- [Bolt.new](https://github.com/pastking/tgbot-verify/blob/main/Boltnew/sheerid_verifier.py): program adapter · Program-specific identity, document, and verifier flow. · `Boltnew/sheerid_verifier.py`
- [YouTube](https://github.com/pastking/tgbot-verify/blob/main/youtube/sheerid_verifier.py): program adapter · Program-specific identity, document, and verifier flow. · `youtube/sheerid_verifier.py`

## Connections

- Telegram → Bot entry point: updates
- Bot entry point → Global policy: loads
- Bot entry point → MySQL persistence: connects
- Bot entry point → User commands: registers
- Bot entry point → Admin commands: registers
- Bot entry point → Verification commands: registers
- User commands → MySQL persistence: reads/writes accounts
- Admin commands → MySQL persistence: admin operations
- Verification commands → MySQL persistence: checks credits
- Verification commands → Global policy: uses verification cost
- Verification commands → Access controls: admission checks
- Verification commands → Concurrency controls: limits work
- Verification commands → Gemini One: selects workflow
- Verification commands → ChatGPT K12: selects workflow
- Verification commands → Spotify: selects workflow
- Verification commands → Bolt.new: selects workflow
- Verification commands → YouTube: selects workflow
- Gemini One → PNG evidence: generates
- ChatGPT K12 → PNG evidence: generates
- Spotify → PNG evidence: generates
- Bolt.new → PNG evidence: generates
- YouTube → PNG evidence: generates
- PNG evidence → SheerID: submitted with identity
- Gemini One → SheerID: API/browser flow
- ChatGPT K12 → SheerID: API/browser flow
- Spotify → SheerID: API/browser flow
- Bolt.new → SheerID: API/browser flow
- YouTube → SheerID: API/browser flow
- SheerID → Partner programs: verification programs
- Container deployment → Bot entry point: runs