# devgaganin/quizbot architecture

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

- Interactive diagram: https://gitdiagram.com/devgaganin/quizbot
- Repository: https://github.com/devgaganin/quizbot

## Overview

Quizbot is a Telegram quiz platform with separate creator and runner bots, a shared MongoDB layer, and an optional FastAPI Mini App. The primary workflow is quiz authoring/import and access setup, followed by quiz delivery, answer scoring, and performance reporting. The README documents additional AI, payment, scheduling, sharing, and broadcast capabilities; their detailed wiring is not fully visible in the sampled source, so those links are shown only where the documented ownership is clear.

Main entry points: [`quizbot/database/repositories.py`](https://github.com/devgaganin/quizbot/blob/main/quizbot/database/repositories.py) (Domain repositories), [`quizbot/runner_bot/handlers/quiz_play.py`](https://github.com/devgaganin/quizbot/blob/main/quizbot/runner_bot/handlers/quiz_play.py) (Quiz sessions), [`quizbot/creator_bot/bot.py`](https://github.com/devgaganin/quizbot/blob/main/quizbot/creator_bot/bot.py) (Creator Bot), [`quizbot/runner_bot/bot.py`](https://github.com/devgaganin/quizbot/blob/main/quizbot/runner_bot/bot.py) (Runner Bot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Quiz authoring"]
  node_creator["Creator Bot<br/>[bot.py]"]
  node_creation["Quiz creation<br/>[quiz_creation.py]"]
  node_imports["Quiz imports<br/>[file_import.py]"]
  node_parsing["Question parsing<br/>[parsing.py]"]
  node_editing["Quiz editing<br/>[quiz_editing.py]"]
  node_management["Quiz management<br/>[quiz_management.py]"]
  node_access["Access and batches<br/>[auth.py]"]
  node_payments["Premium payments<br/>[payments.py]"]
end

subgraph group_delivery["Quiz delivery"]
  node_runner["Runner Bot<br/>[bot.py]"]
  node_quizplay["Quiz sessions<br/>[quiz_play.py]"]
  node_generation["AI quiz generation<br/>[ai_quiz.py]"]
  node_scheduling["Quiz scheduling<br/>[scheduling.py]"]
  node_reports["Analytics and reports<br/>[reports.py]"]
end

subgraph group_data["Shared data"]
  node_db[("MongoDB<br/>[db.py]")]
  node_repositories["Domain repositories<br/>[repositories.py]"]
end

subgraph group_player["Visual player"]
  node_mini_server["Mini App server<br/>[server.py]"]
  node_routes["Player API<br/>[routes.py]"]
  node_player_service["Session and scoring<br/>[player_service.py]"]
end

subgraph group_shared["Shared services"]
  node_reporthtml["HTML scorecards<br/>[quiz_report.py]"]
  node_rich["Rich quiz rendering<br/>[rich_quiz.py]"]
end

node_telegram_user(("Telegram users"))
node_telegram{{"Telegram"}}
node_razorpay{{"Razorpay"}}
node_ai_provider{{"AI providers"}}
node_webapp_user(("Mini App players"))

node_telegram_user -->|"send commands"| node_creator
node_creator -->|"dispatches"| node_creation
node_creator -->|"dispatches"| node_imports
node_creation -->|"parses text"| node_parsing
node_imports -->|"cleans questions"| node_parsing
node_creation -->|"saves quizzes"| node_repositories
node_imports -->|"saves quizzes"| node_repositories
node_editing -->|"updates quizzes"| node_repositories
node_management -->|"manages quizzes"| node_repositories
node_access -->|"manages access"| node_repositories
node_creator -->|"dispatches"| node_payments
node_payments -.->|"processes payments"| node_razorpay
node_telegram_user -->|"play and configure"| node_runner
node_runner -->|"dispatches"| node_quizplay
node_quizplay -->|"loads quiz data"| node_repositories
node_quizplay -->|"sends polls"| node_telegram
node_quizplay -->|"stores results"| node_repositories
node_quizplay -->|"renders rich content"| node_rich
node_runner -->|"dispatches"| node_generation
node_generation -.->|"requests generation"| node_ai_provider
node_runner -->|"dispatches"| node_scheduling
node_reports -->|"reads performance"| node_repositories
node_reports -->|"builds scorecards"| node_reporthtml
node_db -->|"provides collections"| node_repositories
node_webapp_user -->|"opens player"| node_mini_server
node_mini_server -->|"serves API"| node_routes
node_routes -->|"controls sessions"| node_player_service
node_routes -->|"reads quizzes"| node_repositories
node_player_service -->|"persists attempts"| node_repositories
node_routes -->|"authenticates WebApp"| node_telegram

click node_creator "https://github.com/devgaganin/quizbot/blob/main/quizbot/creator_bot/bot.py"
click node_creation "https://github.com/devgaganin/quizbot/blob/main/quizbot/creator_bot/handlers/quiz_creation.py"
click node_imports "https://github.com/devgaganin/quizbot/blob/main/quizbot/creator_bot/handlers/file_import.py"
click node_parsing "https://github.com/devgaganin/quizbot/blob/main/quizbot/creator_bot/parsing.py"
click node_editing "https://github.com/devgaganin/quizbot/blob/main/quizbot/creator_bot/handlers/quiz_editing.py"
click node_management "https://github.com/devgaganin/quizbot/blob/main/quizbot/creator_bot/handlers/quiz_management.py"
click node_access "https://github.com/devgaganin/quizbot/blob/main/quizbot/creator_bot/handlers/auth.py"
click node_payments "https://github.com/devgaganin/quizbot/blob/main/quizbot/creator_bot/handlers/payments.py"
click node_runner "https://github.com/devgaganin/quizbot/blob/main/quizbot/runner_bot/bot.py"
click node_quizplay "https://github.com/devgaganin/quizbot/blob/main/quizbot/runner_bot/handlers/quiz_play.py"
click node_generation "https://github.com/devgaganin/quizbot/blob/main/quizbot/runner_bot/handlers/ai_quiz.py"
click node_scheduling "https://github.com/devgaganin/quizbot/blob/main/quizbot/runner_bot/handlers/scheduling.py"
click node_reports "https://github.com/devgaganin/quizbot/blob/main/quizbot/runner_bot/handlers/reports.py"
click node_reporthtml "https://github.com/devgaganin/quizbot/blob/main/quizbot/shared/html/quiz_report.py"
click node_db "https://github.com/devgaganin/quizbot/blob/main/quizbot/database/db.py"
click node_repositories "https://github.com/devgaganin/quizbot/blob/main/quizbot/database/repositories.py"
click node_mini_server "https://github.com/devgaganin/quizbot/blob/main/quizbot/mini_app/server.py"
click node_routes "https://github.com/devgaganin/quizbot/blob/main/quizbot/mini_app/routes.py"
click node_player_service "https://github.com/devgaganin/quizbot/blob/main/quizbot/mini_app/player_service.py"
click node_rich "https://github.com/devgaganin/quizbot/blob/main/quizbot/shared/rich_quiz.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_creator,node_creation,node_imports,node_parsing,node_editing,node_management,node_access,node_payments,node_telegram_user toneBlue
class node_runner,node_quizplay,node_generation,node_scheduling,node_reports toneAmber
class node_db,node_repositories toneMint
class node_mini_server,node_routes,node_player_service toneRose
class node_reporthtml,node_rich,node_telegram,node_razorpay,node_ai_provider,node_webapp_user toneIndigo
```

## Components

### Quiz authoring

- [Creator Bot](https://github.com/devgaganin/quizbot/blob/main/quizbot/creator_bot/bot.py): `quizbot/creator_bot/bot.py`
- [Quiz creation](https://github.com/devgaganin/quizbot/blob/main/quizbot/creator_bot/handlers/quiz_creation.py): `quizbot/creator_bot/handlers/quiz_creation.py`
- [Quiz imports](https://github.com/devgaganin/quizbot/blob/main/quizbot/creator_bot/handlers/file_import.py): `quizbot/creator_bot/handlers/file_import.py`
- [Question parsing](https://github.com/devgaganin/quizbot/blob/main/quizbot/creator_bot/parsing.py): `quizbot/creator_bot/parsing.py`
- [Quiz editing](https://github.com/devgaganin/quizbot/blob/main/quizbot/creator_bot/handlers/quiz_editing.py): `quizbot/creator_bot/handlers/quiz_editing.py`
- [Quiz management](https://github.com/devgaganin/quizbot/blob/main/quizbot/creator_bot/handlers/quiz_management.py): `quizbot/creator_bot/handlers/quiz_management.py`
- [Access and batches](https://github.com/devgaganin/quizbot/blob/main/quizbot/creator_bot/handlers/auth.py): `quizbot/creator_bot/handlers/auth.py`
- [Premium payments](https://github.com/devgaganin/quizbot/blob/main/quizbot/creator_bot/handlers/payments.py): `quizbot/creator_bot/handlers/payments.py`

### Quiz delivery

- [Runner Bot](https://github.com/devgaganin/quizbot/blob/main/quizbot/runner_bot/bot.py): `quizbot/runner_bot/bot.py`
- [Quiz sessions](https://github.com/devgaganin/quizbot/blob/main/quizbot/runner_bot/handlers/quiz_play.py): `quizbot/runner_bot/handlers/quiz_play.py`
- [AI quiz generation](https://github.com/devgaganin/quizbot/blob/main/quizbot/runner_bot/handlers/ai_quiz.py): `quizbot/runner_bot/handlers/ai_quiz.py`
- [Quiz scheduling](https://github.com/devgaganin/quizbot/blob/main/quizbot/runner_bot/handlers/scheduling.py): `quizbot/runner_bot/handlers/scheduling.py`
- [Analytics and reports](https://github.com/devgaganin/quizbot/blob/main/quizbot/runner_bot/handlers/reports.py): `quizbot/runner_bot/handlers/reports.py`

### Shared data

- [MongoDB](https://github.com/devgaganin/quizbot/blob/main/quizbot/database/db.py): `quizbot/database/db.py`
- [Domain repositories](https://github.com/devgaganin/quizbot/blob/main/quizbot/database/repositories.py): `quizbot/database/repositories.py`

### Visual player

- [Mini App server](https://github.com/devgaganin/quizbot/blob/main/quizbot/mini_app/server.py): `quizbot/mini_app/server.py`
- [Player API](https://github.com/devgaganin/quizbot/blob/main/quizbot/mini_app/routes.py): `quizbot/mini_app/routes.py`
- [Session and scoring](https://github.com/devgaganin/quizbot/blob/main/quizbot/mini_app/player_service.py): `quizbot/mini_app/player_service.py`

### Shared services

- [HTML scorecards](https://github.com/devgaganin/quizbot/blob/main/quizbot/shared/html/quiz_report.py): `quizbot/shared/html/quiz_report.py`
- [Rich quiz rendering](https://github.com/devgaganin/quizbot/blob/main/quizbot/shared/rich_quiz.py): `quizbot/shared/rich_quiz.py`

### Other components

- **Telegram users**
- **Telegram**
- **Razorpay**
- **AI providers**
- **Mini App players**

## Connections

- Telegram users → Creator Bot: send commands
- Creator Bot → Quiz creation: dispatches
- Creator Bot → Quiz imports: dispatches
- Quiz creation → Question parsing: parses text
- Quiz imports → Question parsing: cleans questions
- Quiz creation → Domain repositories: saves quizzes
- Quiz imports → Domain repositories: saves quizzes
- Quiz editing → Domain repositories: updates quizzes
- Quiz management → Domain repositories: manages quizzes
- Access and batches → Domain repositories: manages access
- Creator Bot → Premium payments: dispatches
- Premium payments → Razorpay: processes payments
- Telegram users → Runner Bot: play and configure
- Runner Bot → Quiz sessions: dispatches
- Quiz sessions → Domain repositories: loads quiz data
- Quiz sessions → Telegram: sends polls
- Quiz sessions → Domain repositories: stores results
- Quiz sessions → Rich quiz rendering: renders rich content
- Runner Bot → AI quiz generation: dispatches
- AI quiz generation → AI providers: requests generation
- Runner Bot → Quiz scheduling: dispatches
- Analytics and reports → Domain repositories: reads performance
- Analytics and reports → HTML scorecards: builds scorecards
- MongoDB → Domain repositories: provides collections
- Mini App players → Mini App server: opens player
- Mini App server → Player API: serves API
- Player API → Session and scoring: controls sessions
- Player API → Domain repositories: reads quizzes
- Session and scoring → Domain repositories: persists attempts
- Player API → Telegram: authenticates WebApp