pastking/tgbot-verify

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.