# filatovuu/notifycat-telegram-bot architecture

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

## Overview

Telegram Parser Bot lets users manage channel-and-keyword subscriptions through a Telegram bot, then monitors those channels with a Telethon user session and sends matching-message alerts by private message. The bot also provides role-limited access, administration of users and subscriptions, private-chat access requests, and support workflows. Redis stores subscriptions and authorization data; bot conversation state is in memory. The graph reflects README capabilities and shown imports/calls; some startup wiring and unsampled admin flows are documented but not verified in source excerpts.

Main entry points: [`bot/bot_commands.py`](https://github.com/filatovuu/notifycat-telegram-bot/blob/main/bot/bot_commands.py) (User commands), [`bot/bot_messages.py`](https://github.com/filatovuu/notifycat-telegram-bot/blob/main/bot/bot_messages.py) (Message workflows), [`bot/bot_callbacks.py`](https://github.com/filatovuu/notifycat-telegram-bot/blob/main/bot/bot_callbacks.py) (Button callbacks), [`bot/bot_app.py`](https://github.com/filatovuu/notifycat-telegram-bot/blob/main/bot/bot_app.py) (Bot application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Bot interaction"]
  node_entrypoint["Service startup<br/>[main.py]"]
  node_bot_app["Bot application<br/>[bot_app.py]"]
  node_commands["User commands<br/>[bot_commands.py]"]
  node_messages["Message workflows<br/>[bot_messages.py]"]
  node_callbacks["Button callbacks<br/>[bot_callbacks.py]"]
  node_views["Menus and lists<br/>[bot_views.py]"]
  node_state["Conversation state<br/>[bot_state.py]"]
  node_translations["Translations<br/>[i18n.py]"]
end

subgraph group_access["Access and administration"]
  node_roles["Role limits<br/>[roles.py]"]
  node_admin_notify["New-user notices<br/>[admin_notify.py]"]
end

subgraph group_monitoring["Channel monitoring"]
  node_user_client["Telegram user client<br/>[user_client.py]"]
end

subgraph group_persistence["Persistence and messaging"]
  node_subscriptions["Subscription store<br/>[store.py]"]
  node_redis_subscriptions[("Redis subscriptions<br/>[redis_store.py]")]
  node_redis_auth[("Redis authorization<br/>[redis_store.py]")]
  node_notifier["Notification sender<br/>[notifier.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

node_user(("Telegram user"))
node_admin(("Telegram admin"))
node_telegram(("Telegram platform"))

node_user -->|"uses bot"| node_bot_app
node_admin -->|"administers"| node_bot_app
node_entrypoint -.->|"starts"| node_bot_app
node_entrypoint -.->|"starts"| node_user_client
node_entrypoint -->|"loads"| node_config
node_bot_app -.->|"registers"| node_commands
node_bot_app -.->|"registers"| node_messages
node_bot_app -.->|"registers"| node_callbacks
node_user -->|"sends commands"| node_commands
node_user -->|"sends messages"| node_messages
node_user -->|"uses buttons"| node_callbacks
node_commands -->|"shows menus"| node_views
node_messages -->|"shows menus"| node_views
node_callbacks -->|"shows lists"| node_views
node_commands -->|"updates"| node_state
node_messages -->|"updates"| node_state
node_callbacks -->|"updates"| node_state
node_commands -->|"checks access"| node_redis_auth
node_messages -->|"manages requests"| node_redis_auth
node_callbacks -->|"manages access"| node_redis_auth
node_commands -->|"checks limits"| node_roles
node_messages -->|"checks limits"| node_roles
node_callbacks -->|"checks roles"| node_roles
node_commands -->|"formats notice"| node_admin_notify
node_messages -->|"checks channel access"| node_user_client
node_commands -->|"manages subscriptions"| node_redis_subscriptions
node_messages -->|"manages subscriptions"| node_redis_subscriptions
node_callbacks -->|"manages subscriptions"| node_redis_subscriptions
node_views -->|"reads metadata"| node_redis_subscriptions
node_user_client -->|"reads subscriptions"| node_redis_subscriptions
node_user_client -->|"sends alerts"| node_notifier
node_notifier -->|"sends messages"| node_telegram
node_bot_app -.->|"registers application"| node_notifier
node_bot_app -->|"serves bot"| node_telegram
node_redis_subscriptions -.->|"shares Redis"| node_redis_auth
node_commands -->|"localizes text"| node_translations
node_messages -->|"localizes text"| node_translations
node_callbacks -->|"localizes text"| node_translations
node_views -->|"localizes labels"| node_translations

click node_entrypoint "https://github.com/filatovuu/notifycat-telegram-bot/blob/main/main.py"
click node_bot_app "https://github.com/filatovuu/notifycat-telegram-bot/blob/main/bot/bot_app.py"
click node_commands "https://github.com/filatovuu/notifycat-telegram-bot/blob/main/bot/bot_commands.py"
click node_messages "https://github.com/filatovuu/notifycat-telegram-bot/blob/main/bot/bot_messages.py"
click node_callbacks "https://github.com/filatovuu/notifycat-telegram-bot/blob/main/bot/bot_callbacks.py"
click node_views "https://github.com/filatovuu/notifycat-telegram-bot/blob/main/bot/bot_views.py"
click node_state "https://github.com/filatovuu/notifycat-telegram-bot/blob/main/bot/bot_state.py"
click node_translations "https://github.com/filatovuu/notifycat-telegram-bot/blob/main/bot/i18n.py"
click node_roles "https://github.com/filatovuu/notifycat-telegram-bot/blob/main/core/roles.py"
click node_admin_notify "https://github.com/filatovuu/notifycat-telegram-bot/blob/main/bot/admin_notify.py"
click node_user_client "https://github.com/filatovuu/notifycat-telegram-bot/blob/main/services/user_client.py"
click node_subscriptions "https://github.com/filatovuu/notifycat-telegram-bot/blob/main/storage/store.py"
click node_redis_subscriptions "https://github.com/filatovuu/notifycat-telegram-bot/blob/main/storage/redis_store.py"
click node_redis_auth "https://github.com/filatovuu/notifycat-telegram-bot/blob/main/storage/redis_store.py"
click node_notifier "https://github.com/filatovuu/notifycat-telegram-bot/blob/main/services/notifier.py"
click node_config "https://github.com/filatovuu/notifycat-telegram-bot/blob/main/core/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_entrypoint,node_bot_app,node_commands,node_messages,node_callbacks,node_views,node_state,node_translations,node_user toneBlue
class node_roles,node_admin_notify toneAmber
class node_user_client toneMint
class node_subscriptions,node_redis_subscriptions,node_redis_auth,node_notifier,node_config toneRose
class node_admin,node_telegram toneIndigo
```

## Components

### Bot interaction

- [Service startup](https://github.com/filatovuu/notifycat-telegram-bot/blob/main/main.py): `main.py`
- [Bot application](https://github.com/filatovuu/notifycat-telegram-bot/blob/main/bot/bot_app.py): `bot/bot_app.py`
- [User commands](https://github.com/filatovuu/notifycat-telegram-bot/blob/main/bot/bot_commands.py): `bot/bot_commands.py`
- [Message workflows](https://github.com/filatovuu/notifycat-telegram-bot/blob/main/bot/bot_messages.py): `bot/bot_messages.py`
- [Button callbacks](https://github.com/filatovuu/notifycat-telegram-bot/blob/main/bot/bot_callbacks.py): `bot/bot_callbacks.py`
- [Menus and lists](https://github.com/filatovuu/notifycat-telegram-bot/blob/main/bot/bot_views.py): `bot/bot_views.py`
- [Conversation state](https://github.com/filatovuu/notifycat-telegram-bot/blob/main/bot/bot_state.py): `bot/bot_state.py`
- [Translations](https://github.com/filatovuu/notifycat-telegram-bot/blob/main/bot/i18n.py): `bot/i18n.py`

### Access and administration

- [Role limits](https://github.com/filatovuu/notifycat-telegram-bot/blob/main/core/roles.py): `core/roles.py`
- [New-user notices](https://github.com/filatovuu/notifycat-telegram-bot/blob/main/bot/admin_notify.py): `bot/admin_notify.py`

### Channel monitoring

- [Telegram user client](https://github.com/filatovuu/notifycat-telegram-bot/blob/main/services/user_client.py): `services/user_client.py`

### Persistence and messaging

- [Subscription store](https://github.com/filatovuu/notifycat-telegram-bot/blob/main/storage/store.py): `storage/store.py`
- [Redis subscriptions](https://github.com/filatovuu/notifycat-telegram-bot/blob/main/storage/redis_store.py): `storage/redis_store.py`
- [Redis authorization](https://github.com/filatovuu/notifycat-telegram-bot/blob/main/storage/redis_store.py): `storage/redis_store.py`
- [Notification sender](https://github.com/filatovuu/notifycat-telegram-bot/blob/main/services/notifier.py): `services/notifier.py`
- [Runtime configuration](https://github.com/filatovuu/notifycat-telegram-bot/blob/main/core/config.py): `core/config.py`

### Other components

- **Telegram user**
- **Telegram admin**
- **Telegram platform**

## Connections

- Telegram user → Bot application: uses bot (evidence: `README.md`)
- Telegram admin → Bot application: administers (evidence: `README.md`)
- Service startup → Bot application: starts (evidence: `main.py`)
- Service startup → Telegram user client: starts (evidence: `main.py`)
- Service startup → Runtime configuration: loads (evidence: `main.py`)
- Bot application → User commands: registers (evidence: `bot/bot_app.py`)
- Bot application → Message workflows: registers (evidence: `bot/bot_app.py`)
- Bot application → Button callbacks: registers (evidence: `bot/bot_app.py`)
- Telegram user → User commands: sends commands (evidence: `README.md`)
- Telegram user → Message workflows: sends messages (evidence: `README.md`)
- Telegram user → Button callbacks: uses buttons (evidence: `README.md`)
- User commands → Menus and lists: shows menus (evidence: `bot/bot_commands.py`)
- Message workflows → Menus and lists: shows menus (evidence: `bot/bot_messages.py`)
- Button callbacks → Menus and lists: shows lists (evidence: `bot/bot_callbacks.py`)
- User commands → Conversation state: updates (evidence: `bot/bot_commands.py`)
- Message workflows → Conversation state: updates (evidence: `bot/bot_messages.py`)
- Button callbacks → Conversation state: updates (evidence: `bot/bot_callbacks.py`)
- User commands → Redis authorization: checks access (evidence: `bot/bot_commands.py`)
- Message workflows → Redis authorization: manages requests (evidence: `bot/bot_messages.py`)
- Button callbacks → Redis authorization: manages access (evidence: `bot/bot_callbacks.py`)
- User commands → Role limits: checks limits (evidence: `bot/bot_commands.py`)
- Message workflows → Role limits: checks limits (evidence: `bot/bot_messages.py`)
- Button callbacks → Role limits: checks roles (evidence: `bot/bot_callbacks.py`)
- User commands → New-user notices: formats notice (evidence: `bot/bot_commands.py`)
- Message workflows → Telegram user client: checks channel access (evidence: `bot/bot_messages.py`)
- User commands → Redis subscriptions: manages subscriptions (evidence: `bot/bot_commands.py`)
- Message workflows → Redis subscriptions: manages subscriptions (evidence: `bot/bot_messages.py`)
- Button callbacks → Redis subscriptions: manages subscriptions (evidence: `bot/bot_callbacks.py`)
- Menus and lists → Redis subscriptions: reads metadata (evidence: `bot/bot_views.py`)
- Telegram user client → Redis subscriptions: reads subscriptions (evidence: `services/user_client.py`)
- Telegram user client → Notification sender: sends alerts (evidence: `README.md`)
- Notification sender → Telegram platform: sends messages (evidence: `services/notifier.py`)
- Bot application → Notification sender: registers application (evidence: `bot/bot_app.py`)
- Bot application → Telegram platform: serves bot (evidence: `README.md`)
- Redis subscriptions → Redis authorization: shares Redis (evidence: `storage/redis_store.py`)
- User commands → Translations: localizes text (evidence: `bot/bot_commands.py`)
- Message workflows → Translations: localizes text (evidence: `bot/bot_messages.py`)
- Button callbacks → Translations: localizes text (evidence: `bot/bot_callbacks.py`)
- Menus and lists → Translations: localizes labels (evidence: `bot/bot_views.py`)
