🎯 Quizbot

• Features
• Architecture
• Prerequisites
• Quick Start
• Configuration Reference
• Running the Platform
  • Run Everything
  • Run One Component Only
  • systemd (VPS, always-on)
• Docker Deployment
• Mini App — the Visual Quiz Player
• Database
• Credits

quizbot/
├── database/            Shared async MongoDB layer
│   ├── db.py             Motor connection manager + automatic index setup
│   └── repositories.py   One repository class per domain (users, quizzes, payments, ...)
│
├── shared/               Code shared by both bots
│   ├── config.py          All configuration & secrets, loaded from .env
│   ├── utils/             Text cleanup, premium checks, async file I/O
│   └── html/              Quiz-report HTML generator (exam UI + analysis)
│
├── creator_bot/          Pyrogram bot — quiz creation, editing, batches, payments
│   ├── bot.py             Client setup + run_creator_bot()
│   └── handlers/          One module per feature area
│
├── runner_bot/           python-telegram-bot bot — playing quizzes, AI generation
│   ├── bot.py             Application setup + run_runner_bot()
│   └── handlers/          One module per feature area
│
└── mini_app/             FastAPI Mini App — the visual "Play" quiz player
    ├── telegram_auth.py   Verifies Telegram WebApp initData (HMAC-SHA256)
    ├── player_service.py  Play-session state, scoring, DB persistence
    ├── routes.py          FastAPI app + /api/* endpoints
    └── static/index.html  Single-file frontend (practice + exam mode UI)

run.py                  Combined launcher — starts both bots (+ Mini App, if configured)
requirements.txt
Procfile                 Heroku process declaration (single web dyno)
Dockerfile / docker-compose.yml
.env.example             Environment variable template

Everything runs from one process (run.py) by default, sharing a single async MongoDB database:

• Creator Bot (Pyrogram) handles quiz creation, editing, imports, batches, and payments.
• Runner Bot (python-telegram-bot) handles quiz sessions — sending polls, tracking answers, building leaderboards.
• Mini App (FastAPI, optional) serves a visual in-Telegram quiz player when a public domain is configured.

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
nano .env          # fill in your values — see Configuration Reference below

python run.py

The database and all its indexes are created automatically on first connect — no manual schema step needed.

All values live in .env (copy from .env.example). Note: you must not expose these values in the repo you fork directly otherwise you may loose your bot, data (securely fill these vars and secret in the environment of the platform you are using)

Rate limits, session timeouts, and other tuning knobs have sensible defaults — see the comments in .env.example for the full list.

python run.py

Starts both bots, and the Mini App server too if MINI_APP_DOMAIN is set.

python run.py --only creator   # Creator Bot only
python run.py --only runner    # Runner Bot only
python run.py --only miniapp   # Mini App server only

sudo nano /etc/systemd/system/quizbot.service

[Unit]
Description=Quizbot Platform
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/opt/quizbot
ExecStart=/opt/quizbot/.venv/bin/python run.py
Restart=always
RestartSec=10
EnvironmentFile=/opt/quizbot/.env
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now quizbot
sudo journalctl -u quizbot -f      # live logs

docker compose up -d --build

This starts the Creator Bot, Runner Bot, and (if MINI_APP_DOMAIN is set) the Mini App as separate containers, each connecting out to the same MongoDB Atlas cluster via MONGODB_URI — no local volume needed, since nothing is stored on the container's own filesystem.

To skip the Mini App entirely:

docker compose up -d --build creator-bot runner-bot

Heroku / other PaaS: a single Procfile (web: python run.py) runs the whole platform from one dyno/process — set the same .env variables as Config Vars.

A "Play" button (opened as a Telegram WebApp) appears after quiz creation and on inline-share cards, offering two modes:

• Practice mode — instant correct/incorrect feedback with the explanation shown right after each answer, then auto-advance.
• Exam mode — no answers revealed until the end, followed by a full top-to-bottom review of every question, your answer, the correct answer, and the explanation.

It's strictly a player — no creation or editing happens here, and it enforces the same access rules as both bots (free/paid quizzes, batch access, auth-chat lists, optional premium gate).

Telegram requires a public HTTPS URL for WebApp buttons, so put a reverse proxy or tunnel (nginx, Caddy, Cloudflare Tunnel, etc.) in front of the FastAPI server and set MINI_APP_DOMAIN accordingly. Leave it blank to disable the feature entirely — no Play buttons are shown, and the server doesn't start.

Identity comes solely from Telegram's own initData, verified server-side via HMAC-SHA256 on every request. Quiz content in every API response is AES-256-GCM encrypted with a per-session key, and the correct answer is never present in a question's payload before it's answered.

Data lives in MongoDB Atlas — a free M0 cluster is enough to get started (see Quick Start). quizbot/database/db.py connects via Motor and creates every required index automatically on first connect, so there's no manual schema step. Both bots read and write through repository classes in quizbot/database/repositories.py — there's no separate API layer to keep in sync.