# axellorwave/gosha architecture

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

- Interactive diagram: https://gitdiagram.com/axellorwave/gosha
- Repository: https://github.com/axellorwave/gosha

## Overview

Гоша is a Telegram group-chat bot whose central workflow is: Telegram updates reach registered handlers, handlers apply chat/profile/statistics/moderation or event logic, and the repository persists state in PostgreSQL before the bot replies or sends scheduled messages. The graph preserves the documented birthdays, backups, broadcasts, secret words, logs, and tic-tac-toe branches. Source excerpts are partial; documented capabilities are included, while uncertain internal links are omitted rather than inferred.

Main entry points: [`gosha/handlers`](https://github.com/axellorwave/gosha/tree/master/gosha/handlers) (Handler registration), [`gosha/db/repo.py`](https://github.com/axellorwave/gosha/blob/master/gosha/db/repo.py) (Data access), [`gosha/services/event_sender.py`](https://github.com/axellorwave/gosha/blob/master/gosha/services/event_sender.py) (Event delivery), [`gosha/handlers/games.py`](https://github.com/axellorwave/gosha/blob/master/gosha/handlers/games.py) (Tic-tac-toe)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Bot runtime"]
  node_runtime["Bot startup<br/>[__main__.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
  node_dispatch["Handler registration"]
  node_states["Dialog state<br/>[states.py]"]
end

subgraph group_interaction["Chat features"]
  node_tracking["Message tracking<br/>[tracking.py]"]
  node_stats["Statistics<br/>[stats.py]"]
  node_profiles["Profiles<br/>[profile.py]"]
  node_admin["Administration<br/>[admin.py]"]
  node_membership["Membership changes<br/>[membership.py]"]
  node_moderation["Moderation<br/>[moderation.py]"]
  node_secretwords["Secret words<br/>[secrets.py]"]
  node_games["Tic-tac-toe<br/>[games.py]"]
  node_gameengine["Game engine<br/>[tictactoe.py]"]
  node_rich["Rich-message adapter<br/>[rich.py]"]
end

subgraph group_events["Events and messaging"]
  node_eventhandlers["Event management<br/>[events.py]"]
  node_eventlogic["Event scheduling logic<br/>[events.py]"]
  node_sender["Event delivery<br/>[event_sender.py]"]
  node_birthdays["Birthday service<br/>[birthdays.py]"]
  node_broadcast["Broadcasts<br/>[broadcast.py]"]
  node_commands["Command menus<br/>[commands.py]"]
end

subgraph group_persistence["Persistence"]
  node_repo["Data access<br/>[repo.py]"]
  node_models["Domain records<br/>[models.py]"]
  node_database[("PostgreSQL")]
end

subgraph group_operations["Operations"]
  node_backup["Backup and restore<br/>[backups.py]"]
  node_backuphandler["Backup controls<br/>[backups.py]"]
  node_logs["Log management<br/>[logs.py]"]
  node_loghandler["Log controls<br/>[logs.py]"]
  node_formatting["Message formatting<br/>[formatting.py]"]
end

node_member(("Group members"))
node_owner(("Bot owner"))
node_telegram{{"Telegram Bot API"}}

node_member -->|"sends updates"| node_telegram
node_owner -->|"sends commands"| node_telegram
node_telegram -->|"delivers updates"| node_dispatch
node_runtime -->|"loads"| node_settings
node_runtime -->|"registers"| node_dispatch
node_runtime -->|"starts scheduler"| node_sender
node_runtime -->|"starts backup service"| node_backup
node_dispatch -->|"registers dispatcher"| node_states
node_dispatch -->|"registers"| node_tracking
node_dispatch -->|"registers"| node_stats
node_dispatch -->|"registers"| node_profiles
node_dispatch -->|"registers"| node_admin
node_dispatch -->|"registers"| node_membership
node_dispatch -->|"registers"| node_moderation
node_dispatch -->|"registers"| node_secretwords
node_dispatch -->|"registers"| node_games
node_dispatch -->|"registers"| node_eventhandlers
node_dispatch -->|"registers"| node_broadcast
node_tracking -->|"records activity"| node_repo
node_stats -->|"queries totals"| node_repo
node_profiles -->|"reads profile"| node_repo
node_admin -->|"updates settings"| node_repo
node_membership -->|"updates membership"| node_repo
node_moderation -->|"moderates users"| node_telegram
node_secretwords -.->|"manages words"| node_repo
node_games -->|"runs game rules"| node_gameengine
node_games -->|"renders rich game"| node_rich
node_games -->|"loads and saves games"| node_repo
node_games -->|"sends game messages"| node_telegram
node_eventhandlers -->|"uses event logic"| node_eventlogic
node_eventhandlers -->|"requests preview"| node_sender
node_eventhandlers -->|"manages birthdays"| node_birthdays
node_eventhandlers -->|"syncs commands"| node_commands
node_sender -->|"evaluates schedule"| node_eventlogic
node_sender -->|"builds birthday content"| node_birthdays
node_sender -->|"loads due events"| node_repo
node_sender -->|"sends messages"| node_telegram
node_birthdays -->|"maintains birthday events"| node_repo
node_broadcast -->|"sends broadcasts"| node_telegram
node_broadcast -->|"selects recipients"| node_repo
node_commands -->|"publishes menus"| node_telegram
node_backuphandler -->|"controls backup"| node_backup
node_backup -->|"exports and restores"| node_database
node_loghandler -->|"requests log ranges"| node_logs
node_loghandler -->|"sends log files"| node_telegram
node_repo -->|"queries records"| node_models
node_repo -->|"reads and writes"| node_database
node_models -->|"maps tables"| node_database

click node_runtime "https://github.com/axellorwave/gosha/blob/master/gosha/__main__.py"
click node_settings "https://github.com/axellorwave/gosha/blob/master/gosha/config.py"
click node_dispatch "https://github.com/axellorwave/gosha/tree/master/gosha/handlers"
click node_states "https://github.com/axellorwave/gosha/blob/master/gosha/handlers/states.py"
click node_tracking "https://github.com/axellorwave/gosha/blob/master/gosha/handlers/tracking.py"
click node_stats "https://github.com/axellorwave/gosha/blob/master/gosha/handlers/stats.py"
click node_profiles "https://github.com/axellorwave/gosha/blob/master/gosha/handlers/profile.py"
click node_admin "https://github.com/axellorwave/gosha/blob/master/gosha/handlers/admin.py"
click node_membership "https://github.com/axellorwave/gosha/blob/master/gosha/handlers/membership.py"
click node_moderation "https://github.com/axellorwave/gosha/blob/master/gosha/handlers/moderation.py"
click node_secretwords "https://github.com/axellorwave/gosha/blob/master/gosha/handlers/secrets.py"
click node_games "https://github.com/axellorwave/gosha/blob/master/gosha/handlers/games.py"
click node_gameengine "https://github.com/axellorwave/gosha/blob/master/gosha/services/tictactoe.py"
click node_rich "https://github.com/axellorwave/gosha/blob/master/gosha/services/rich.py"
click node_eventhandlers "https://github.com/axellorwave/gosha/blob/master/gosha/handlers/events.py"
click node_eventlogic "https://github.com/axellorwave/gosha/blob/master/gosha/services/events.py"
click node_sender "https://github.com/axellorwave/gosha/blob/master/gosha/services/event_sender.py"
click node_birthdays "https://github.com/axellorwave/gosha/blob/master/gosha/services/birthdays.py"
click node_broadcast "https://github.com/axellorwave/gosha/blob/master/gosha/handlers/broadcast.py"
click node_commands "https://github.com/axellorwave/gosha/blob/master/gosha/services/commands.py"
click node_repo "https://github.com/axellorwave/gosha/blob/master/gosha/db/repo.py"
click node_models "https://github.com/axellorwave/gosha/blob/master/gosha/db/models.py"
click node_backup "https://github.com/axellorwave/gosha/blob/master/gosha/services/backups.py"
click node_backuphandler "https://github.com/axellorwave/gosha/blob/master/gosha/handlers/backups.py"
click node_logs "https://github.com/axellorwave/gosha/blob/master/gosha/services/logs.py"
click node_loghandler "https://github.com/axellorwave/gosha/blob/master/gosha/handlers/logs.py"
click node_formatting "https://github.com/axellorwave/gosha/blob/master/gosha/services/formatting.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_runtime,node_settings,node_dispatch,node_states toneBlue
class node_tracking,node_stats,node_profiles,node_admin,node_membership,node_moderation,node_secretwords,node_games,node_gameengine,node_rich toneAmber
class node_eventhandlers,node_eventlogic,node_sender,node_birthdays,node_broadcast,node_commands,node_telegram toneMint
class node_repo,node_models,node_database toneRose
class node_backup,node_backuphandler,node_logs,node_loghandler,node_formatting,node_member,node_owner toneIndigo
```

## Components

### Bot runtime

- [Bot startup](https://github.com/axellorwave/gosha/blob/master/gosha/__main__.py): `gosha/__main__.py`
- [Runtime settings](https://github.com/axellorwave/gosha/blob/master/gosha/config.py): `gosha/config.py`
- [Handler registration](https://github.com/axellorwave/gosha/tree/master/gosha/handlers): `gosha/handlers`
- [Dialog state](https://github.com/axellorwave/gosha/blob/master/gosha/handlers/states.py): `gosha/handlers/states.py`

### Chat features

- [Message tracking](https://github.com/axellorwave/gosha/blob/master/gosha/handlers/tracking.py): `gosha/handlers/tracking.py`
- [Statistics](https://github.com/axellorwave/gosha/blob/master/gosha/handlers/stats.py): `gosha/handlers/stats.py`
- [Profiles](https://github.com/axellorwave/gosha/blob/master/gosha/handlers/profile.py): `gosha/handlers/profile.py`
- [Administration](https://github.com/axellorwave/gosha/blob/master/gosha/handlers/admin.py): `gosha/handlers/admin.py`
- [Membership changes](https://github.com/axellorwave/gosha/blob/master/gosha/handlers/membership.py): `gosha/handlers/membership.py`
- [Moderation](https://github.com/axellorwave/gosha/blob/master/gosha/handlers/moderation.py): `gosha/handlers/moderation.py`
- [Secret words](https://github.com/axellorwave/gosha/blob/master/gosha/handlers/secrets.py): `gosha/handlers/secrets.py`
- [Tic-tac-toe](https://github.com/axellorwave/gosha/blob/master/gosha/handlers/games.py): `gosha/handlers/games.py`
- [Game engine](https://github.com/axellorwave/gosha/blob/master/gosha/services/tictactoe.py): `gosha/services/tictactoe.py`
- [Rich-message adapter](https://github.com/axellorwave/gosha/blob/master/gosha/services/rich.py): `gosha/services/rich.py`

### Events and messaging

- [Event management](https://github.com/axellorwave/gosha/blob/master/gosha/handlers/events.py): `gosha/handlers/events.py`
- [Event scheduling logic](https://github.com/axellorwave/gosha/blob/master/gosha/services/events.py): `gosha/services/events.py`
- [Event delivery](https://github.com/axellorwave/gosha/blob/master/gosha/services/event_sender.py): `gosha/services/event_sender.py`
- [Birthday service](https://github.com/axellorwave/gosha/blob/master/gosha/services/birthdays.py): `gosha/services/birthdays.py`
- [Broadcasts](https://github.com/axellorwave/gosha/blob/master/gosha/handlers/broadcast.py): `gosha/handlers/broadcast.py`
- [Command menus](https://github.com/axellorwave/gosha/blob/master/gosha/services/commands.py): `gosha/services/commands.py`

### Persistence

- [Data access](https://github.com/axellorwave/gosha/blob/master/gosha/db/repo.py): `gosha/db/repo.py`
- [Domain records](https://github.com/axellorwave/gosha/blob/master/gosha/db/models.py): `gosha/db/models.py`
- **PostgreSQL**

### Operations

- [Backup and restore](https://github.com/axellorwave/gosha/blob/master/gosha/services/backups.py): `gosha/services/backups.py`
- [Backup controls](https://github.com/axellorwave/gosha/blob/master/gosha/handlers/backups.py): `gosha/handlers/backups.py`
- [Log management](https://github.com/axellorwave/gosha/blob/master/gosha/services/logs.py): `gosha/services/logs.py`
- [Log controls](https://github.com/axellorwave/gosha/blob/master/gosha/handlers/logs.py): `gosha/handlers/logs.py`
- [Message formatting](https://github.com/axellorwave/gosha/blob/master/gosha/services/formatting.py): `gosha/services/formatting.py`

### Other components

- **Group members**
- **Bot owner**
- **Telegram Bot API**

## Connections

- Group members → Telegram Bot API: sends updates (evidence: `README.md`)
- Bot owner → Telegram Bot API: sends commands (evidence: `README.md`)
- Telegram Bot API → Handler registration: delivers updates
- Bot startup → Runtime settings: loads (evidence: `gosha/__main__.py`)
- Bot startup → Handler registration: registers (evidence: `gosha/__main__.py`)
- Bot startup → Event delivery: starts scheduler (evidence: `gosha/__main__.py`)
- Bot startup → Backup and restore: starts backup service (evidence: `gosha/__main__.py`)
- Handler registration → Dialog state: registers dispatcher (evidence: `gosha/handlers/__init__.py`)
- Handler registration → Message tracking: registers (evidence: `gosha/handlers/__init__.py`)
- Handler registration → Statistics: registers (evidence: `gosha/handlers/__init__.py`)
- Handler registration → Profiles: registers (evidence: `gosha/handlers/__init__.py`)
- Handler registration → Administration: registers (evidence: `gosha/handlers/__init__.py`)
- Handler registration → Membership changes: registers (evidence: `gosha/handlers/__init__.py`)
- Handler registration → Moderation: registers (evidence: `gosha/handlers/__init__.py`)
- Handler registration → Secret words: registers (evidence: `gosha/handlers/__init__.py`)
- Handler registration → Tic-tac-toe: registers (evidence: `gosha/handlers/__init__.py`)
- Handler registration → Event management: registers (evidence: `gosha/handlers/__init__.py`)
- Handler registration → Broadcasts: registers (evidence: `gosha/handlers/__init__.py`)
- Message tracking → Data access: records activity (evidence: `gosha/handlers/tracking.py`)
- Statistics → Data access: queries totals (evidence: `gosha/handlers/stats.py`)
- Profiles → Data access: reads profile (evidence: `gosha/handlers/profile.py`)
- Administration → Data access: updates settings (evidence: `gosha/handlers/admin.py`)
- Membership changes → Data access: updates membership (evidence: `gosha/handlers/membership.py`)
- Moderation → Telegram Bot API: moderates users (evidence: `README.md`)
- Secret words → Data access: manages words
- Tic-tac-toe → Game engine: runs game rules (evidence: `gosha/handlers/games.py`)
- Tic-tac-toe → Rich-message adapter: renders rich game (evidence: `gosha/handlers/games.py`)
- Tic-tac-toe → Data access: loads and saves games (evidence: `gosha/handlers/games.py`)
- Tic-tac-toe → Telegram Bot API: sends game messages (evidence: `gosha/handlers/games.py`)
- Event management → Event scheduling logic: uses event logic (evidence: `gosha/handlers/events.py`)
- Event management → Event delivery: requests preview (evidence: `gosha/handlers/events.py`)
- Event management → Birthday service: manages birthdays (evidence: `gosha/handlers/events.py`)
- Event management → Command menus: syncs commands (evidence: `gosha/handlers/events.py`)
- Event delivery → Event scheduling logic: evaluates schedule (evidence: `gosha/services/event_sender.py`)
- Event delivery → Birthday service: builds birthday content (evidence: `gosha/services/event_sender.py`)
- Event delivery → Data access: loads due events (evidence: `gosha/services/event_sender.py`)
- Event delivery → Telegram Bot API: sends messages (evidence: `gosha/services/event_sender.py`)
- Birthday service → Data access: maintains birthday events (evidence: `gosha/services/birthdays.py`)
- Broadcasts → Telegram Bot API: sends broadcasts (evidence: `README.md`)
- Broadcasts → Data access: selects recipients (evidence: `gosha/handlers/broadcast.py`)
- Command menus → Telegram Bot API: publishes menus (evidence: `gosha/services/commands.py`)
- Backup controls → Backup and restore: controls backup (evidence: `gosha/handlers/backups.py`)
- Backup and restore → PostgreSQL: exports and restores (evidence: `README.md`)
- Log controls → Log management: requests log ranges (evidence: `gosha/handlers/logs.py`)
- Log controls → Telegram Bot API: sends log files (evidence: `gosha/handlers/logs.py`)
- Data access → Domain records: queries records (evidence: `gosha/db/repo.py`)
- Data access → PostgreSQL: reads and writes (evidence: `gosha/db/repo.py`)
- Domain records → PostgreSQL: maps tables (evidence: `gosha/db/models.py`)
