# drtnn/telegram-secretary-bot architecture

> Architecture diagram of the GitHub repository drtnn/telegram-secretary-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/drtnn/telegram-secretary-bot
- Repository: https://github.com/drtnn/telegram-secretary-bot

## Overview

This is a Telegram secretary bot that records users’ business-chat messages and notifies the connected user when messages are edited or deleted; it also saves and relays media. The visible runtime starts polling, registers business-message and private-command handlers, persists user/message records, and periodically removes old records and cached files. The README provides no further capability documentation. Edges reflect shown calls and imports; dispatch from Telegram and some content-helper details are not fully shown.

Main entry points: [`app/database/repositories.py`](https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/database/repositories.py) (Data repositories), [`app/utils/content.py`](https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/utils/content.py) (Message content operations), [`app/loader.py`](https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/loader.py) (Bot wiring), [`app/controller/business_message.py`](https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/controller/business_message.py) (Business handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_main["Polling startup<br/>[main.py]"]
  node_loader["Bot wiring<br/>[loader.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

subgraph group_handlers["Telegram handlers"]
  node_business["Business handlers"]
  node_private["Private start handler<br/>[private.py]"]
end

subgraph group_content["Message processing"]
  node_content_ops["Message content operations<br/>[content.py]"]
  node_patterns["Message templates<br/>[patterns.py]"]
  node_markups["User link markup<br/>[markups.py]"]
  node_cleanup["Scheduled cleanup<br/>[content.py]"]
end

subgraph group_persistence["Persistence and files"]
  node_storage["Filesystem storage<br/>[storage.py]"]
  node_repositories["Data repositories<br/>[repositories.py]"]
  node_models["User and message models<br/>[models.py]"]
  node_sessions["Database sessions<br/>[session.py]"]
end

node_chat_users(("Chat users"))
node_telegram{{"Telegram API"}}
node_postgres[("PostgreSQL")]

node_chat_users -.->|"send messages"| node_telegram
node_telegram -.->|"delivers business events"| node_business
node_telegram -.->|"delivers commands"| node_private
node_main -->|"registers router"| node_business
node_main -->|"registers router"| node_private
node_main -->|"starts polling"| node_loader
node_main -->|"starts task"| node_cleanup
node_business -->|"creates and looks up records"| node_repositories
node_business -->|"saves and relays messages"| node_content_ops
node_business -->|"gets business connection"| node_loader
node_private -->|"creates user record"| node_repositories
node_private -->|"uses start text"| node_patterns
node_content_ops -->|"stores and retrieves messages"| node_repositories
node_content_ops -->|"uses bot and storage"| node_loader
node_content_ops -->|"uses message templates"| node_patterns
node_content_ops -->|"uses user markup"| node_markups
node_content_ops -->|"downloads and sends content"| node_telegram
node_cleanup -->|"deletes old records"| node_repositories
node_cleanup -->|"deletes cached files"| node_storage
node_repositories -->|"queries models"| node_models
node_repositories -->|"uses session wrapper"| node_sessions
node_sessions -->|"gets database URL"| node_settings
node_sessions -->|"opens database connection"| node_postgres
node_loader -->|"instantiates repositories"| node_repositories
node_loader -->|"instantiates storage"| node_storage
node_loader -->|"configures bot"| node_settings

click node_main "https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/main.py"
click node_loader "https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/loader.py"
click node_business "https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/controller/business_message.py"
click node_private "https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/controller/private.py"
click node_content_ops "https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/utils/content.py"
click node_patterns "https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/utils/patterns.py"
click node_markups "https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/utils/markups.py"
click node_cleanup "https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/utils/content.py"
click node_storage "https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/utils/storage.py"
click node_repositories "https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/database/repositories.py"
click node_models "https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/database/models.py"
click node_sessions "https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/database/session.py"
click node_settings "https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/config.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_main,node_loader,node_settings,node_chat_users toneBlue
class node_business,node_private,node_postgres toneAmber
class node_content_ops,node_patterns,node_markups,node_cleanup,node_telegram toneMint
class node_storage,node_repositories,node_models,node_sessions toneRose
```

## Components

### Bot runtime

- [Polling startup](https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/main.py): `app/main.py`
- [Bot wiring](https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/loader.py): `app/loader.py`
- [Runtime settings](https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/config.py): `app/config.py`

### Telegram handlers

- [Business handlers](https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/controller/business_message.py): `app/controller/business_message.py`
- [Private start handler](https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/controller/private.py): `app/controller/private.py`

### Message processing

- [Message content operations](https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/utils/content.py): `app/utils/content.py`
- [Message templates](https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/utils/patterns.py): `app/utils/patterns.py`
- [User link markup](https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/utils/markups.py): `app/utils/markups.py`
- [Scheduled cleanup](https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/utils/content.py): `app/utils/content.py`

### Persistence and files

- [Filesystem storage](https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/utils/storage.py): `app/utils/storage.py`
- [Data repositories](https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/database/repositories.py): `app/database/repositories.py`
- [User and message models](https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/database/models.py): `app/database/models.py`
- [Database sessions](https://github.com/drtnn/telegram-secretary-bot/blob/develop/app/database/session.py): `app/database/session.py`

### Other components

- **Chat users**
- **Telegram API**
- **PostgreSQL**

## Connections

- Chat users → Telegram API: send messages
- Telegram API → Business handlers: delivers business events
- Telegram API → Private start handler: delivers commands
- Polling startup → Business handlers: registers router (evidence: `app/main.py`)
- Polling startup → Private start handler: registers router (evidence: `app/main.py`)
- Polling startup → Bot wiring: starts polling (evidence: `app/main.py`)
- Polling startup → Scheduled cleanup: starts task (evidence: `app/main.py`)
- Business handlers → Data repositories: creates and looks up records (evidence: `app/controller/business_message.py`)
- Business handlers → Message content operations: saves and relays messages (evidence: `app/controller/business_message.py`)
- Business handlers → Bot wiring: gets business connection (evidence: `app/controller/business_message.py`)
- Private start handler → Data repositories: creates user record (evidence: `app/controller/private.py`)
- Private start handler → Message templates: uses start text (evidence: `app/controller/private.py`)
- Message content operations → Data repositories: stores and retrieves messages (evidence: `app/utils/content.py`)
- Message content operations → Bot wiring: uses bot and storage (evidence: `app/utils/content.py`)
- Message content operations → Message templates: uses message templates (evidence: `app/utils/content.py`)
- Message content operations → User link markup: uses user markup (evidence: `app/utils/content.py`)
- Message content operations → Telegram API: downloads and sends content (evidence: `app/utils/content.py`)
- Scheduled cleanup → Data repositories: deletes old records (evidence: `app/utils/content.py`)
- Scheduled cleanup → Filesystem storage: deletes cached files (evidence: `app/utils/content.py`)
- Data repositories → User and message models: queries models (evidence: `app/database/repositories.py`)
- Data repositories → Database sessions: uses session wrapper (evidence: `app/database/repositories.py`)
- Database sessions → Runtime settings: gets database URL (evidence: `app/database/session.py`)
- Database sessions → PostgreSQL: opens database connection (evidence: `app/database/session.py`)
- Bot wiring → Data repositories: instantiates repositories (evidence: `app/loader.py`)
- Bot wiring → Filesystem storage: instantiates storage (evidence: `app/loader.py`)
- Bot wiring → Runtime settings: configures bot (evidence: `app/loader.py`)
