# drotyk/btwseptember architecture

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

- Interactive diagram: https://gitdiagram.com/drotyk/btwseptember
- Repository: https://github.com/drotyk/btwseptember

## Overview

BTW is a Telegram registration bot paired with a protected admin panel. The main participant workflow is private-chat registration: collect and validate participant details, training selections, and consent; persist the completed form and resumable session in PostgreSQL. Administrators authenticate to manage registrations, speakers, and scheduled notifications, while a worker delivers notifications through Telegram. README capabilities provide the broad subsystem map; sampled source confirms startup, session storage, authentication, speaker services, and notification delivery, but not every handler-to-service route.

Main entry points: [`src/bot/handlers`](https://github.com/drotyk/btwseptember/tree/main/src/bot/handlers) (Bot handlers), [`src/web.ts`](https://github.com/drotyk/btwseptember/blob/main/src/web.ts) (HTTP panel and APIs), [`src/main.ts`](https://github.com/drotyk/btwseptember/blob/main/src/main.ts) (Application startup), [`src/bot/create-bot.ts`](https://github.com/drotyk/btwseptember/blob/main/src/bot/create-bot.ts) (Bot setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_registration["Registration bot"]
  node_bot["Bot setup<br/>[create-bot.ts]"]
  node_handlers["Bot handlers"]
  node_registration_state["Registration state"]
  node_registration_service["Registration rules"]
  node_form["Training form<br/>[form.ts]"]
  node_rules["Rules and consent<br/>[rules.service.ts]"]
end

subgraph group_admin["Admin panel"]
  node_web["HTTP panel and APIs<br/>[web.ts]"]
  node_auth["Admin authentication<br/>[auth.ts]"]
  node_admin_ui["Admin interface<br/>[app.js]"]
end

subgraph group_communications["Speakers and messaging"]
  node_speaker_service["Speaker management<br/>[speaker.service.ts]"]
  node_telegram_speakers["Speaker carousel"]
  node_worker["Notification worker"]
end

subgraph group_data["Persistence and runtime"]
  node_main["Application startup<br/>[main.ts]"]
  node_users[("Participant records")]
  node_sessions[("Bot sessions")]
  node_admin_sessions[("Admin sessions")]
  node_speakers[("Speaker records")]
  node_notifications[("Notification records")]
  node_migrations["Schema migrations<br/>[migrations.ts]"]
end

node_participant(("Participant"))
node_telegram{{"Telegram API"}}
node_administrator(("Administrator"))
node_browser(("Admin browser"))
node_postgres[("PostgreSQL")]

node_participant -->|"sends updates"| node_telegram
node_telegram -->|"delivers updates"| node_bot
node_main -->|"creates bot"| node_bot
node_bot -->|"dispatches updates"| node_handlers
node_handlers -->|"advances steps"| node_registration_state
node_handlers -->|"submits registration"| node_registration_service
node_registration_service -->|"checks training IDs"| node_form
node_handlers -->|"handles rules"| node_rules
node_registration_service -->|"saves participant"| node_users
node_bot -->|"stores resumable state"| node_sessions
node_administrator -->|"uses panel"| node_browser
node_browser -->|"calls panel APIs"| node_web
node_web -->|"checks access"| node_auth
node_auth -->|"validates sessions"| node_admin_sessions
node_web -->|"serves registration data"| node_users
node_web -->|"manages speakers"| node_speaker_service
node_speaker_service -->|"reads and writes"| node_speakers
node_handlers -->|"handles speaker actions"| node_telegram_speakers
node_telegram_speakers -->|"loads active speakers"| node_speakers
node_telegram_speakers -->|"sends carousel"| node_telegram
node_web -->|"manages notifications"| node_notifications
node_main -->|"starts worker"| node_worker
node_worker -->|"claims and updates deliveries"| node_notifications
node_worker -->|"sends messages"| node_telegram
node_main -->|"runs migrations"| node_migrations
node_main -->|"creates database pool"| node_postgres
node_users -->|"queries records"| node_postgres
node_sessions -->|"queries sessions"| node_postgres
node_admin_sessions -->|"queries sessions"| node_postgres
node_speakers -->|"queries speakers"| node_postgres
node_notifications -->|"queries deliveries"| node_postgres

click node_main "https://github.com/drotyk/btwseptember/blob/main/src/main.ts"
click node_bot "https://github.com/drotyk/btwseptember/blob/main/src/bot/create-bot.ts"
click node_handlers "https://github.com/drotyk/btwseptember/tree/main/src/bot/handlers"
click node_registration_state "https://github.com/drotyk/btwseptember/blob/main/src/bot/registration-state.ts"
click node_registration_service "https://github.com/drotyk/btwseptember/blob/main/src/services/registration.service.ts"
click node_form "https://github.com/drotyk/btwseptember/blob/main/src/form.ts"
click node_rules "https://github.com/drotyk/btwseptember/blob/main/src/services/rules.service.ts"
click node_web "https://github.com/drotyk/btwseptember/blob/main/src/web.ts"
click node_auth "https://github.com/drotyk/btwseptember/blob/main/src/web/auth.ts"
click node_admin_ui "https://github.com/drotyk/btwseptember/blob/main/public/app.js"
click node_speaker_service "https://github.com/drotyk/btwseptember/blob/main/src/services/speaker.service.ts"
click node_telegram_speakers "https://github.com/drotyk/btwseptember/blob/main/src/services/telegram-speaker.service.ts"
click node_worker "https://github.com/drotyk/btwseptember/blob/main/src/workers/notification.worker.ts"
click node_users "https://github.com/drotyk/btwseptember/blob/main/src/repositories/users.repository.ts"
click node_sessions "https://github.com/drotyk/btwseptember/blob/main/src/repositories/sessions.repository.ts"
click node_admin_sessions "https://github.com/drotyk/btwseptember/blob/main/src/repositories/admin-sessions.repository.ts"
click node_speakers "https://github.com/drotyk/btwseptember/blob/main/src/repositories/speakers.repository.ts"
click node_notifications "https://github.com/drotyk/btwseptember/blob/main/src/repositories/notifications.repository.ts"
click node_migrations "https://github.com/drotyk/btwseptember/blob/main/src/migrations.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_bot,node_handlers,node_registration_state,node_registration_service,node_form,node_rules,node_browser toneBlue
class node_web,node_auth,node_admin_ui,node_postgres toneAmber
class node_speaker_service,node_telegram_speakers,node_worker,node_telegram toneMint
class node_main,node_users,node_sessions,node_admin_sessions,node_speakers,node_notifications,node_migrations toneRose
class node_participant,node_administrator toneIndigo
```

## Components

### Registration bot

- [Bot setup](https://github.com/drotyk/btwseptember/blob/main/src/bot/create-bot.ts): `src/bot/create-bot.ts`
- [Bot handlers](https://github.com/drotyk/btwseptember/tree/main/src/bot/handlers): `src/bot/handlers`
- [Registration state](https://github.com/drotyk/btwseptember/blob/main/src/bot/registration-state.ts): `src/bot/registration-state.ts`
- [Registration rules](https://github.com/drotyk/btwseptember/blob/main/src/services/registration.service.ts): `src/services/registration.service.ts`
- [Training form](https://github.com/drotyk/btwseptember/blob/main/src/form.ts): `src/form.ts`
- [Rules and consent](https://github.com/drotyk/btwseptember/blob/main/src/services/rules.service.ts): `src/services/rules.service.ts`

### Admin panel

- [HTTP panel and APIs](https://github.com/drotyk/btwseptember/blob/main/src/web.ts): `src/web.ts`
- [Admin authentication](https://github.com/drotyk/btwseptember/blob/main/src/web/auth.ts): `src/web/auth.ts`
- [Admin interface](https://github.com/drotyk/btwseptember/blob/main/public/app.js): `public/app.js`

### Speakers and messaging

- [Speaker management](https://github.com/drotyk/btwseptember/blob/main/src/services/speaker.service.ts): `src/services/speaker.service.ts`
- [Speaker carousel](https://github.com/drotyk/btwseptember/blob/main/src/services/telegram-speaker.service.ts): `src/services/telegram-speaker.service.ts`
- [Notification worker](https://github.com/drotyk/btwseptember/blob/main/src/workers/notification.worker.ts): `src/workers/notification.worker.ts`

### Persistence and runtime

- [Application startup](https://github.com/drotyk/btwseptember/blob/main/src/main.ts): `src/main.ts`
- [Participant records](https://github.com/drotyk/btwseptember/blob/main/src/repositories/users.repository.ts): `src/repositories/users.repository.ts`
- [Bot sessions](https://github.com/drotyk/btwseptember/blob/main/src/repositories/sessions.repository.ts): `src/repositories/sessions.repository.ts`
- [Admin sessions](https://github.com/drotyk/btwseptember/blob/main/src/repositories/admin-sessions.repository.ts): `src/repositories/admin-sessions.repository.ts`
- [Speaker records](https://github.com/drotyk/btwseptember/blob/main/src/repositories/speakers.repository.ts): `src/repositories/speakers.repository.ts`
- [Notification records](https://github.com/drotyk/btwseptember/blob/main/src/repositories/notifications.repository.ts): `src/repositories/notifications.repository.ts`
- [Schema migrations](https://github.com/drotyk/btwseptember/blob/main/src/migrations.ts): `src/migrations.ts`

### Other components

- **Participant**
- **Telegram API**
- **Administrator**
- **Admin browser**
- **PostgreSQL**

## Connections

- Participant → Telegram API: sends updates
- Telegram API → Bot setup: delivers updates
- Application startup → Bot setup: creates bot
- Bot setup → Bot handlers: dispatches updates
- Bot handlers → Registration state: advances steps
- Bot handlers → Registration rules: submits registration
- Registration rules → Training form: checks training IDs
- Bot handlers → Rules and consent: handles rules
- Registration rules → Participant records: saves participant
- Bot setup → Bot sessions: stores resumable state
- Administrator → Admin browser: uses panel
- Admin browser → HTTP panel and APIs: calls panel APIs
- HTTP panel and APIs → Admin authentication: checks access
- Admin authentication → Admin sessions: validates sessions
- HTTP panel and APIs → Participant records: serves registration data
- HTTP panel and APIs → Speaker management: manages speakers
- Speaker management → Speaker records: reads and writes
- Bot handlers → Speaker carousel: handles speaker actions
- Speaker carousel → Speaker records: loads active speakers
- Speaker carousel → Telegram API: sends carousel
- HTTP panel and APIs → Notification records: manages notifications
- Application startup → Notification worker: starts worker
- Notification worker → Notification records: claims and updates deliveries
- Notification worker → Telegram API: sends messages
- Application startup → Schema migrations: runs migrations
- Application startup → PostgreSQL: creates database pool
- Participant records → PostgreSQL: queries records
- Bot sessions → PostgreSQL: queries sessions
- Admin sessions → PostgreSQL: queries sessions
- Speaker records → PostgreSQL: queries speakers
- Notification records → PostgreSQL: queries deliveries