# thetisiboth/dot architecture

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

- Interactive diagram: https://gitdiagram.com/thetisiboth/dot
- Repository: https://github.com/thetisiboth/dot

## Overview

Ultimate Frisbee Training Bot schedules seasonal practices and sends Telegram announcements, attendance checks, and optional rules quizzes. The main workflow runs from bot startup through scheduling, season-specific training details, message generation, and Telegram delivery; later attendance checks read reactions and may remind the team or notify trainers. Commands provide previews, manual sends, and quiz controls. Separate branches cover the rules-question bank and health monitoring. The README documents MTProto reaction reading and optional Ollama generation; sampled source excerpts show only parts of their wiring, so some integration links are documented rather than source-verified.

Main entry points: [`src/app.ts`](https://github.com/thetisiboth/dot/blob/main/src/app.ts) (Application startup), [`src/services/RulesQuizService.ts`](https://github.com/thetisiboth/dot/blob/main/src/services/RulesQuizService.ts) (Quiz orchestration), [`src/services/SchedulerService.ts`](https://github.com/thetisiboth/dot/blob/main/src/services/SchedulerService.ts) (Training scheduler), [`src/commands/registry.ts`](https://github.com/thetisiboth/dot/blob/main/src/commands/registry.ts) (Command routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_app["Application startup<br/>[app.ts]"]
  node_config["Configuration<br/>[index.ts]"]
  node_command_registry["Command routing<br/>[registry.ts]"]
  node_public_commands["Public commands<br/>[public.ts]"]
  node_training_commands["Training commands<br/>[training.ts]"]
  node_quiz_commands["Quiz commands<br/>[quiz.ts]"]
  node_health["Health endpoints<br/>[HealthServer.ts]"]
end

subgraph group_training["Training workflow"]
  node_scheduler["Training scheduler"]
  node_season["Season planning<br/>[SeasonManager.ts]"]
  node_generator["Message generation"]
  node_telegram_helpers["Telegram delivery helpers<br/>[telegram.ts]"]
end

subgraph group_attendance["Attendance tracking"]
  node_reaction_reader["Reaction reader<br/>[ReactionReader.ts]"]
end

subgraph group_quiz["Rules quiz"]
  node_quiz_service["Quiz orchestration"]
  node_quiz_bank["Question bank<br/>[annotations.ts]"]
  node_quiz_picker["Quiz selection and posts<br/>[quizPicker.ts]"]
  node_quiz_answer["Quiz answers<br/>[quizAnswer.ts]"]
  node_quiz_data["Quiz source data<br/>[index.ts]"]
end

node_admin(("Admin"))
node_telegram_users(("Telegram users"))
node_telegram{{"Telegram Bot API"}}
node_mtproto{{"MTProto account"}}
node_ollama{{"Ollama"}}

node_admin -->|"sends commands"| node_telegram
node_telegram_users -->|"reacts to posts"| node_telegram
node_app -->|"loads"| node_config
node_app -->|"registers"| node_command_registry
node_app -->|"starts"| node_scheduler
node_app -->|"creates"| node_season
node_app -->|"creates"| node_generator
node_app -->|"creates"| node_reaction_reader
node_app -->|"creates"| node_quiz_service
node_app -->|"starts"| node_health
node_command_registry -->|"routes updates"| node_telegram
node_command_registry -.->|"dispatches"| node_public_commands
node_command_registry -.->|"dispatches"| node_training_commands
node_command_registry -.->|"dispatches"| node_quiz_commands
node_public_commands -->|"queries schedule"| node_season
node_training_commands -->|"requests sends"| node_scheduler
node_training_commands -->|"previews messages"| node_generator
node_scheduler -->|"gets training details"| node_season
node_scheduler -->|"generates messages"| node_generator
node_scheduler -->|"checks reactions"| node_reaction_reader
node_scheduler -->|"schedules quiz"| node_quiz_service
node_scheduler -->|"sends announcements"| node_telegram
node_generator -.->|"formats fallback delivery"| node_telegram_helpers
node_generator -.->|"generates optionally"| node_ollama
node_reaction_reader -.->|"reads reactions"| node_mtproto
node_reaction_reader -.->|"checks bot messages"| node_telegram
node_quiz_commands -->|"requests quiz actions"| node_quiz_service
node_quiz_service -->|"selects season mode"| node_season
node_quiz_service -->|"builds quiz post"| node_quiz_picker
node_quiz_service -->|"builds answers"| node_quiz_answer
node_quiz_service -->|"looks up questions"| node_quiz_data
node_quiz_data -->|"assembles question sets"| node_quiz_bank
node_quiz_service -->|"posts polls"| node_telegram

click node_app "https://github.com/thetisiboth/dot/blob/main/src/app.ts"
click node_config "https://github.com/thetisiboth/dot/blob/main/src/config/index.ts"
click node_command_registry "https://github.com/thetisiboth/dot/blob/main/src/commands/registry.ts"
click node_public_commands "https://github.com/thetisiboth/dot/blob/main/src/commands/public.ts"
click node_training_commands "https://github.com/thetisiboth/dot/blob/main/src/commands/training.ts"
click node_quiz_commands "https://github.com/thetisiboth/dot/blob/main/src/commands/quiz.ts"
click node_health "https://github.com/thetisiboth/dot/blob/main/src/services/HealthServer.ts"
click node_scheduler "https://github.com/thetisiboth/dot/blob/main/src/services/SchedulerService.ts"
click node_season "https://github.com/thetisiboth/dot/blob/main/src/services/SeasonManager.ts"
click node_generator "https://github.com/thetisiboth/dot/blob/main/src/services/MessageGenerator.ts"
click node_telegram_helpers "https://github.com/thetisiboth/dot/blob/main/src/utils/telegram.ts"
click node_reaction_reader "https://github.com/thetisiboth/dot/blob/main/src/services/ReactionReader.ts"
click node_quiz_service "https://github.com/thetisiboth/dot/blob/main/src/services/RulesQuizService.ts"
click node_quiz_bank "https://github.com/thetisiboth/dot/blob/main/src/data/rules-quiz/annotations.ts"
click node_quiz_picker "https://github.com/thetisiboth/dot/blob/main/src/services/quizPicker.ts"
click node_quiz_answer "https://github.com/thetisiboth/dot/blob/main/src/services/quizAnswer.ts"
click node_quiz_data "https://github.com/thetisiboth/dot/blob/main/src/data/rules-quiz/index.ts"

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_app,node_config,node_command_registry,node_public_commands,node_training_commands,node_quiz_commands,node_health,node_telegram_users toneBlue
class node_scheduler,node_season,node_generator,node_telegram_helpers toneAmber
class node_reaction_reader,node_telegram toneMint
class node_quiz_service,node_quiz_bank,node_quiz_picker,node_quiz_answer,node_quiz_data toneRose
class node_admin,node_mtproto,node_ollama toneIndigo
```

## Components

### Bot runtime

- [Application startup](https://github.com/thetisiboth/dot/blob/main/src/app.ts): `src/app.ts`
- [Configuration](https://github.com/thetisiboth/dot/blob/main/src/config/index.ts): `src/config/index.ts`
- [Command routing](https://github.com/thetisiboth/dot/blob/main/src/commands/registry.ts): `src/commands/registry.ts`
- [Public commands](https://github.com/thetisiboth/dot/blob/main/src/commands/public.ts): `src/commands/public.ts`
- [Training commands](https://github.com/thetisiboth/dot/blob/main/src/commands/training.ts): `src/commands/training.ts`
- [Quiz commands](https://github.com/thetisiboth/dot/blob/main/src/commands/quiz.ts): `src/commands/quiz.ts`
- [Health endpoints](https://github.com/thetisiboth/dot/blob/main/src/services/HealthServer.ts): `src/services/HealthServer.ts`

### Training workflow

- [Training scheduler](https://github.com/thetisiboth/dot/blob/main/src/services/SchedulerService.ts): `src/services/SchedulerService.ts`
- [Season planning](https://github.com/thetisiboth/dot/blob/main/src/services/SeasonManager.ts): `src/services/SeasonManager.ts`
- [Message generation](https://github.com/thetisiboth/dot/blob/main/src/services/MessageGenerator.ts): `src/services/MessageGenerator.ts`
- [Telegram delivery helpers](https://github.com/thetisiboth/dot/blob/main/src/utils/telegram.ts): `src/utils/telegram.ts`

### Attendance tracking

- [Reaction reader](https://github.com/thetisiboth/dot/blob/main/src/services/ReactionReader.ts): `src/services/ReactionReader.ts`

### Rules quiz

- [Quiz orchestration](https://github.com/thetisiboth/dot/blob/main/src/services/RulesQuizService.ts): `src/services/RulesQuizService.ts`
- [Question bank](https://github.com/thetisiboth/dot/blob/main/src/data/rules-quiz/annotations.ts): `src/data/rules-quiz/annotations.ts`
- [Quiz selection and posts](https://github.com/thetisiboth/dot/blob/main/src/services/quizPicker.ts): `src/services/quizPicker.ts`
- [Quiz answers](https://github.com/thetisiboth/dot/blob/main/src/services/quizAnswer.ts): `src/services/quizAnswer.ts`
- [Quiz source data](https://github.com/thetisiboth/dot/blob/main/src/data/rules-quiz/index.ts): `src/data/rules-quiz/index.ts`

### Other components

- **Admin**
- **Telegram users**
- **Telegram Bot API**
- **MTProto account**
- **Ollama**

## Connections

- Admin → Telegram Bot API: sends commands (evidence: `README.md`)
- Telegram users → Telegram Bot API: reacts to posts (evidence: `README.md`)
- Application startup → Configuration: loads (evidence: `src/app.ts`)
- Application startup → Command routing: registers (evidence: `src/app.ts`)
- Application startup → Training scheduler: starts (evidence: `src/app.ts`)
- Application startup → Season planning: creates (evidence: `src/app.ts`)
- Application startup → Message generation: creates (evidence: `src/app.ts`)
- Application startup → Reaction reader: creates (evidence: `src/app.ts`)
- Application startup → Quiz orchestration: creates (evidence: `src/app.ts`)
- Application startup → Health endpoints: starts (evidence: `src/app.ts`)
- Command routing → Telegram Bot API: routes updates (evidence: `src/commands/registry.ts`)
- Command routing → Public commands: dispatches (evidence: `src/commands/public.ts`)
- Command routing → Training commands: dispatches (evidence: `src/commands/training.ts`)
- Command routing → Quiz commands: dispatches (evidence: `src/commands/quiz.ts`)
- Public commands → Season planning: queries schedule (evidence: `src/commands/public.ts`)
- Training commands → Training scheduler: requests sends (evidence: `src/commands/training.ts`)
- Training commands → Message generation: previews messages (evidence: `src/commands/training.ts`)
- Training scheduler → Season planning: gets training details (evidence: `src/services/SchedulerService.ts`)
- Training scheduler → Message generation: generates messages (evidence: `src/services/SchedulerService.ts`)
- Training scheduler → Reaction reader: checks reactions (evidence: `src/services/SchedulerService.ts`)
- Training scheduler → Quiz orchestration: schedules quiz (evidence: `src/services/SchedulerService.ts`)
- Training scheduler → Telegram Bot API: sends announcements (evidence: `README.md`)
- Message generation → Telegram delivery helpers: formats fallback delivery
- Message generation → Ollama: generates optionally (evidence: `README.md`)
- Reaction reader → MTProto account: reads reactions (evidence: `README.md`)
- Reaction reader → Telegram Bot API: checks bot messages (evidence: `README.md`)
- Quiz commands → Quiz orchestration: requests quiz actions (evidence: `src/commands/quiz.ts`)
- Quiz orchestration → Season planning: selects season mode (evidence: `src/services/RulesQuizService.ts`)
- Quiz orchestration → Quiz selection and posts: builds quiz post (evidence: `src/services/RulesQuizService.ts`)
- Quiz orchestration → Quiz answers: builds answers (evidence: `src/services/RulesQuizService.ts`)
- Quiz orchestration → Quiz source data: looks up questions (evidence: `src/services/RulesQuizService.ts`)
- Quiz source data → Question bank: assembles question sets (evidence: `src/data/rules-quiz/index.ts`)
- Quiz orchestration → Telegram Bot API: posts polls (evidence: `src/services/RulesQuizService.ts`)
