# maxxsalov/golova_na_meste_bot architecture

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

- Interactive diagram: https://gitdiagram.com/maxxsalov/golova_na_meste_bot
- Repository: https://github.com/maxxsalov/golova_na_meste_bot

## Overview

This is a Telegram reminder bot for shared chats. Members register, send natural-language reminder requests, and receive scheduled chat notifications with controls to mark done or snooze. Separate handlers support reminder lists and management, timezone and quiet-mode settings, statistics, help/FAQ, and inline commands. The main bot process registers the handlers; a separate scheduler polls overdue reminders. Relationships below follow shown imports, calls, and router registration; unsampled behavior is represented only where documented in the README.

Main entry points: [`bot/main.py`](https://github.com/maxxsalov/golova_na_meste_bot/blob/main/bot/main.py) (Bot entry), [`db/repository.py`](https://github.com/maxxsalov/golova_na_meste_bot/blob/main/db/repository.py) (Reminder repository), [`bot/handlers/misc.py`](https://github.com/maxxsalov/golova_na_meste_bot/blob/main/bot/handlers/misc.py) (Chat settings), [`scheduler/jobs.py`](https://github.com/maxxsalov/golova_na_meste_bot/blob/main/scheduler/jobs.py) (Reminder dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bot["Telegram bot"]
  node_bot_main["Bot entry<br/>[main.py]"]
  node_config["Settings<br/>[config.py]"]
  node_registration["Registration<br/>[registration.py]"]
  node_misc["Chat settings<br/>[misc.py]"]
  node_inline["Inline commands<br/>[inline.py]"]
  node_content["Help and FAQ<br/>[content.py]"]
end

subgraph group_reminders["Reminder workflow"]
  node_reminder_handler["Reminder commands<br/>[reminders.py]"]
  node_parser["Message parser<br/>[parser.py]"]
  node_callbacks["Reminder actions<br/>[callbacks.py]"]
end

subgraph group_data["Persistence"]
  node_database["DB sessions<br/>[database.py]"]
  node_repository["Reminder repository<br/>[repository.py]"]
  node_models["Domain models<br/>[models.py]"]
  node_sql_store[("SQL database")]
end

subgraph group_scheduler["Scheduled delivery"]
  node_scheduler_main["Scheduler entry<br/>[main.py]"]
  node_jobs["Reminder dispatch<br/>[jobs.py]"]
end

node_members(("Chat members"))
node_telegram["Telegram API"]

node_members -->|"send commands"| node_telegram
node_telegram -->|"deliver updates"| node_bot_main
node_bot_main -->|"loads settings"| node_config
node_bot_main -->|"creates sessions"| node_database
node_bot_main -->|"registers router"| node_registration
node_bot_main -->|"registers router"| node_reminder_handler
node_bot_main -->|"registers router"| node_callbacks
node_bot_main -->|"registers router"| node_misc
node_bot_main -->|"registers router"| node_inline
node_registration -->|"uses"| node_repository
node_reminder_handler -->|"parses messages"| node_parser
node_reminder_handler -->|"resolves and saves"| node_repository
node_reminder_handler -->|"replies"| node_telegram
node_callbacks -->|"updates status"| node_repository
node_callbacks -->|"uses FAQ"| node_content
node_callbacks -->|"edits messages"| node_telegram
node_misc -->|"manages settings"| node_repository
node_misc -->|"queries statistics"| node_models
node_misc -->|"serves FAQ"| node_content
node_misc -->|"replies"| node_telegram
node_inline -->|"filters commands"| node_content
node_repository -->|"queries entities"| node_models
node_bot_main -.->|"connects"| node_sql_store
node_scheduler_main -->|"loads settings"| node_config
node_scheduler_main -->|"creates sessions"| node_database
node_scheduler_main -->|"schedules every 30s"| node_jobs
node_jobs -->|"finds overdue"| node_repository
node_jobs -->|"loads reminder details"| node_models
node_jobs -->|"gets action keyboard"| node_callbacks
node_jobs -->|"sends notifications"| node_telegram

click node_bot_main "https://github.com/maxxsalov/golova_na_meste_bot/blob/main/bot/main.py"
click node_config "https://github.com/maxxsalov/golova_na_meste_bot/blob/main/bot/config.py"
click node_registration "https://github.com/maxxsalov/golova_na_meste_bot/blob/main/bot/handlers/registration.py"
click node_reminder_handler "https://github.com/maxxsalov/golova_na_meste_bot/blob/main/bot/handlers/reminders.py"
click node_parser "https://github.com/maxxsalov/golova_na_meste_bot/blob/main/bot/parser.py"
click node_callbacks "https://github.com/maxxsalov/golova_na_meste_bot/blob/main/bot/handlers/callbacks.py"
click node_misc "https://github.com/maxxsalov/golova_na_meste_bot/blob/main/bot/handlers/misc.py"
click node_inline "https://github.com/maxxsalov/golova_na_meste_bot/blob/main/bot/handlers/inline.py"
click node_content "https://github.com/maxxsalov/golova_na_meste_bot/blob/main/bot/content.py"
click node_database "https://github.com/maxxsalov/golova_na_meste_bot/blob/main/db/database.py"
click node_repository "https://github.com/maxxsalov/golova_na_meste_bot/blob/main/db/repository.py"
click node_models "https://github.com/maxxsalov/golova_na_meste_bot/blob/main/db/models.py"
click node_scheduler_main "https://github.com/maxxsalov/golova_na_meste_bot/blob/main/scheduler/main.py"
click node_jobs "https://github.com/maxxsalov/golova_na_meste_bot/blob/main/scheduler/jobs.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_bot_main,node_config,node_registration,node_misc,node_inline,node_content toneBlue
class node_reminder_handler,node_parser,node_callbacks toneAmber
class node_database,node_repository,node_models,node_sql_store,node_telegram toneMint
class node_scheduler_main,node_jobs toneRose
class node_members toneIndigo
```

## Components

### Telegram bot

- [Bot entry](https://github.com/maxxsalov/golova_na_meste_bot/blob/main/bot/main.py): `bot/main.py`
- [Settings](https://github.com/maxxsalov/golova_na_meste_bot/blob/main/bot/config.py): `bot/config.py`
- [Registration](https://github.com/maxxsalov/golova_na_meste_bot/blob/main/bot/handlers/registration.py): `bot/handlers/registration.py`
- [Chat settings](https://github.com/maxxsalov/golova_na_meste_bot/blob/main/bot/handlers/misc.py): `bot/handlers/misc.py`
- [Inline commands](https://github.com/maxxsalov/golova_na_meste_bot/blob/main/bot/handlers/inline.py): `bot/handlers/inline.py`
- [Help and FAQ](https://github.com/maxxsalov/golova_na_meste_bot/blob/main/bot/content.py): `bot/content.py`

### Reminder workflow

- [Reminder commands](https://github.com/maxxsalov/golova_na_meste_bot/blob/main/bot/handlers/reminders.py): `bot/handlers/reminders.py`
- [Message parser](https://github.com/maxxsalov/golova_na_meste_bot/blob/main/bot/parser.py): `bot/parser.py`
- [Reminder actions](https://github.com/maxxsalov/golova_na_meste_bot/blob/main/bot/handlers/callbacks.py): `bot/handlers/callbacks.py`

### Persistence

- [DB sessions](https://github.com/maxxsalov/golova_na_meste_bot/blob/main/db/database.py): `db/database.py`
- [Reminder repository](https://github.com/maxxsalov/golova_na_meste_bot/blob/main/db/repository.py): `db/repository.py`
- [Domain models](https://github.com/maxxsalov/golova_na_meste_bot/blob/main/db/models.py): `db/models.py`
- **SQL database**

### Scheduled delivery

- [Scheduler entry](https://github.com/maxxsalov/golova_na_meste_bot/blob/main/scheduler/main.py): `scheduler/main.py`
- [Reminder dispatch](https://github.com/maxxsalov/golova_na_meste_bot/blob/main/scheduler/jobs.py): `scheduler/jobs.py`

### Other components

- **Chat members**
- **Telegram API**

## Connections

- Chat members → Telegram API: send commands (evidence: `README.md`)
- Telegram API → Bot entry: deliver updates (evidence: `bot/main.py`)
- Bot entry → Settings: loads settings (evidence: `bot/main.py`)
- Bot entry → DB sessions: creates sessions (evidence: `bot/main.py`)
- Bot entry → Registration: registers router (evidence: `bot/main.py`)
- Bot entry → Reminder commands: registers router (evidence: `bot/main.py`)
- Bot entry → Reminder actions: registers router (evidence: `bot/main.py`)
- Bot entry → Chat settings: registers router (evidence: `bot/main.py`)
- Bot entry → Inline commands: registers router (evidence: `bot/main.py`)
- Registration → Reminder repository: uses (evidence: `bot/handlers/registration.py`)
- Reminder commands → Message parser: parses messages (evidence: `bot/handlers/reminders.py`)
- Reminder commands → Reminder repository: resolves and saves (evidence: `bot/handlers/reminders.py`)
- Reminder commands → Telegram API: replies (evidence: `bot/handlers/reminders.py`)
- Reminder actions → Reminder repository: updates status (evidence: `bot/handlers/callbacks.py`)
- Reminder actions → Help and FAQ: uses FAQ (evidence: `bot/handlers/callbacks.py`)
- Reminder actions → Telegram API: edits messages (evidence: `bot/handlers/callbacks.py`)
- Chat settings → Reminder repository: manages settings (evidence: `bot/handlers/misc.py`)
- Chat settings → Domain models: queries statistics (evidence: `bot/handlers/misc.py`)
- Chat settings → Help and FAQ: serves FAQ (evidence: `bot/handlers/misc.py`)
- Chat settings → Telegram API: replies (evidence: `bot/handlers/misc.py`)
- Inline commands → Help and FAQ: filters commands (evidence: `bot/handlers/inline.py`)
- Reminder repository → Domain models: queries entities (evidence: `db/repository.py`)
- Bot entry → SQL database: connects
- Scheduler entry → Settings: loads settings (evidence: `scheduler/main.py`)
- Scheduler entry → DB sessions: creates sessions (evidence: `scheduler/main.py`)
- Scheduler entry → Reminder dispatch: schedules every 30s (evidence: `scheduler/main.py`)
- Reminder dispatch → Reminder repository: finds overdue (evidence: `scheduler/jobs.py`)
- Reminder dispatch → Domain models: loads reminder details (evidence: `scheduler/jobs.py`)
- Reminder dispatch → Reminder actions: gets action keyboard (evidence: `scheduler/jobs.py`)
- Reminder dispatch → Telegram API: sends notifications (evidence: `scheduler/jobs.py`)
