# v-kisielius/media-holder-bot architecture

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

- Interactive diagram: https://gitdiagram.com/v-kisielius/media-holder-bot
- Repository: https://github.com/v-kisielius/media-holder-bot

## Overview

1. **Overall shape**
   - This is a single-purpose Telegram bot, written in Python and built around `python-telegram-bot`.
   - The repository is organized as a small application core plus a few support modules, with Docker files for deployment.

2. **Runtime entrypoints**
   - `bot.py` is the top-level launcher for local execution.
   - `bot/main.py` appears to be the actual bootstrapper that creates the bot application, registers handlers, and starts polling or another Telegram update loop.
   - `entrypoint.sh` and `docker-compose.yml` wrap the same startup path in containers.

3. **Configuration boundary**
   - `config.py` centralizes environment-driven settings such as `BOT_TOKEN`, `USER_ID`, `CHANNEL_ID`, and any path overrides like `SIGNATURES_FILE`.
   - The `.env.example` file shows that secrets and runtime targets are injected from the environment, not hardcoded.
   - This means the bot’s behavior is controlled externally, which is important for deployment diagrams.

4. **Update handling layer**
   - `bot/handlers.py` is the main interaction layer.
   - It likely contains handlers for `/start`, `/help`, incoming media messages, and settings-related interactions.
   - This layer is the primary boundary between Telegram updates and the application’s business logic.

5. **Media processing pipeline**
   - The core feature is to receive forwarded media, strip captions/sender metadata, and resend the content cleanly.
   - The readme notes that it uses Telegram `file_id` forwarding, so the bot does not re-upload or transcode media, which preserves quality.
   - This processing is likely coordinated between handlers and utility functions in `bot/utils.py`.

6. **Authorization and access control**
   - The bot is restricted to a configured user ID.
   - `handlers.py` or a utility module likely checks that incoming requests come from the authorized user before allowing any action.
   - This is an important security boundary: anonymous Telegram users interact with the bot, but only one authorized operator is allowed to use it.

7. **Output routing**
   - Cleaned media is sent either back to the user in direct messages or to a configured channel.
   - `CHANNEL_ID` is optional, so the bot supports two output modes: private delivery or channel posting.
   - The channel is an external Telegram destination and must grant the bot admin/post permissions.

8. **UI and interaction model**
   - `bot/keyboards.py` suggests inline or reply keyboards for settings and quick actions.
   - The readme mentions a settings path for adding default signatures, so the bot likely exposes a small conversational settings UI rather than a web interface.
   - `/start` and `/help` are the only explicit command-level UX surfaces described.

9. **State and persistence**
   - `bot/storage.py` likely manages the bot’s local persisted state, especially signatures.
   - The readme says signatures are stored in `signatures.json` or a path defined by `SIGNATURES_FILE`, which implies file-based persistence rather than a database.
   - That file is the main durable state boundary in the repo.

10. **Domain utilities**
   - `bot/utils.py` probably contains shared helpers for media-type detection, caption cleanup, formatting, and album/group handling.
   - The readme states that albums are preserved, so there is probably logic here or in handlers to track grouped media updates and resend them as a unit.

11. **Deployment and packaging**
   - `Dockerfile`, `docker-compose.yml`, and `entrypoint.sh` define the containerized runtime.
   - `requirements.txt` pins the Python dependencies, with `python-telegram-bot` and `python-dotenv` being the key runtime libraries.
   - The repo supports both local execution and container deployment with the same application code.

12. **External dependencies and data flow**
   - Main external service: Telegram Bot API.
   - Main data inputs: incoming Telegram updates, environment variables, and the signatures JSON file.
   - Main data outputs: cleaned Telegram messages/media sent to a private chat or channel.

13. **Architectural summary for a diagram**
   - At the center is the bot application loop in `bot/main.py`.
   - Incoming Telegram updates flow into `bot/handlers.py`, which delegates to `utils.py` for media/caption logic and `storage.py` for persisted signatures/settings.
   - Outbound results go back through Telegram to either the authorized user or a configured channel.
   - Docker and environment configuration sit outside the app as deployment/runtime infrastructure.

Main entry points: [`bot/handlers.py`](https://github.com/v-kisielius/media-holder-bot/blob/main/bot/handlers.py) (Handlers), [`bot/main.py`](https://github.com/v-kisielius/media-holder-bot/blob/main/bot/main.py) (Main loop), [`config.py`](https://github.com/v-kisielius/media-holder-bot/blob/main/config.py) (Config), [`bot/storage.py`](https://github.com/v-kisielius/media-holder-bot/blob/main/bot/storage.py) (Storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_bot_py["bot.py<br/>launcher<br/>[bot.py]"]
  node_main["Main loop<br/>bootstrapper<br/>[main.py]"]
end

subgraph group_app["Application"]
  node_handlers["Handlers<br/>[handlers.py]"]
  node_keyboards["Keyboards<br/>ui helpers<br/>[keyboards.py]"]
  node_utils["Utils<br/>media helpers<br/>[utils.py]"]
  node_storage[("Storage<br/>file state<br/>[storage.py]")]
end

subgraph group_deploy["Deployment"]
  node_config["Config<br/>[config.py]"]
  node_entrypoint["Entrypoint<br/>container entry<br/>[entrypoint.sh]"]
  node_compose["Compose<br/>service spec<br/>[docker-compose.yml]"]
  node_dockerfile["Dockerfile<br/>image build"]
  node_requirements["Requirements<br/>deps lock<br/>[requirements.txt]"]
  node_env_example["Env example<br/>sample config<br/>[.env.example]"]
end

node_telegram_api(("Telegram API<br/>external service"))
node_authorized_user(("Operator<br/>trusted user"))
node_target_channel(("Channel<br/>telegram destination"))
node_signatures_file[("Signatures JSON<br/>persistent state")]

node_bot_py -->|"starts"| node_main
node_entrypoint -->|"runs"| node_main
node_compose -->|"invokes"| node_entrypoint
node_dockerfile -->|"installs"| node_requirements
node_main -->|"loads"| node_config
node_main -->|"registers"| node_handlers
node_handlers -->|"uses"| node_keyboards
node_handlers -->|"delegates"| node_utils
node_handlers -->|"reads/writes"| node_storage
node_storage -->|"persists"| node_signatures_file
node_main -->|"connects"| node_telegram_api
node_telegram_api -->|"delivers updates"| node_handlers
node_handlers -->|"checks access"| node_authorized_user
node_handlers -->|"posts to"| node_target_channel
node_config -->|"defines"| node_authorized_user
node_config -->|"defines"| node_target_channel
node_config -->|"defines"| node_signatures_file
node_env_example -->|"documents"| node_config

click node_bot_py "https://github.com/v-kisielius/media-holder-bot/blob/main/bot.py"
click node_main "https://github.com/v-kisielius/media-holder-bot/blob/main/bot/main.py"
click node_handlers "https://github.com/v-kisielius/media-holder-bot/blob/main/bot/handlers.py"
click node_keyboards "https://github.com/v-kisielius/media-holder-bot/blob/main/bot/keyboards.py"
click node_utils "https://github.com/v-kisielius/media-holder-bot/blob/main/bot/utils.py"
click node_storage "https://github.com/v-kisielius/media-holder-bot/blob/main/bot/storage.py"
click node_config "https://github.com/v-kisielius/media-holder-bot/blob/main/config.py"
click node_entrypoint "https://github.com/v-kisielius/media-holder-bot/blob/main/entrypoint.sh"
click node_compose "https://github.com/v-kisielius/media-holder-bot/blob/main/docker-compose.yml"
click node_dockerfile "https://github.com/v-kisielius/media-holder-bot/tree/main/Dockerfile"
click node_requirements "https://github.com/v-kisielius/media-holder-bot/blob/main/requirements.txt"
click node_env_example "https://github.com/v-kisielius/media-holder-bot/blob/main/.env.example"

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_py,node_main toneBlue
class node_handlers,node_keyboards,node_utils,node_storage toneAmber
class node_config,node_entrypoint,node_compose,node_dockerfile,node_requirements,node_env_example toneMint
class node_telegram_api,node_authorized_user,node_target_channel,node_signatures_file toneNeutral
```

## Components

### Runtime

Bot startup and update loop

- [bot.py](https://github.com/v-kisielius/media-holder-bot/blob/main/bot.py): launcher · Top-level local entrypoint · `bot.py`
- [Main loop](https://github.com/v-kisielius/media-holder-bot/blob/main/bot/main.py): bootstrapper · Creates the Telegram application and starts polling · `bot/main.py`

### Application

Core bot logic and domain modules

- [Handlers](https://github.com/v-kisielius/media-holder-bot/blob/main/bot/handlers.py): update handlers · Routes Telegram updates into bot actions · `bot/handlers.py`
- [Keyboards](https://github.com/v-kisielius/media-holder-bot/blob/main/bot/keyboards.py): ui helpers · Inline or reply keyboard definitions · `bot/keyboards.py`
- [Utils](https://github.com/v-kisielius/media-holder-bot/blob/main/bot/utils.py): media helpers · Caption cleanup, media handling, album logic · `bot/utils.py`
- [Storage](https://github.com/v-kisielius/media-holder-bot/blob/main/bot/storage.py): file state · Persists signatures and local bot state · `bot/storage.py`

### Deployment

Container and environment packaging

- [Config](https://github.com/v-kisielius/media-holder-bot/blob/main/config.py): env config · Loads token, IDs, and file paths from environment · `config.py`
- [Entrypoint](https://github.com/v-kisielius/media-holder-bot/blob/main/entrypoint.sh): container entry · Container startup script · `entrypoint.sh`
- [Compose](https://github.com/v-kisielius/media-holder-bot/blob/main/docker-compose.yml): service spec · Container orchestration for local or server deployment · `docker-compose.yml`
- [Dockerfile](https://github.com/v-kisielius/media-holder-bot/tree/main/Dockerfile): image build · Builds the bot runtime image · `Dockerfile`
- [Requirements](https://github.com/v-kisielius/media-holder-bot/blob/main/requirements.txt): deps lock · Python dependency set including Telegram and dotenv · `requirements.txt`
- [Env example](https://github.com/v-kisielius/media-holder-bot/blob/main/.env.example): sample config · Example variables for bot token, user, channel, and paths · `.env.example`

### Other components

- **Telegram API**: external service · Receives updates and serves outbound bot messages
- **Operator**: trusted user · Configured Telegram user allowed to control the bot
- **Channel**: telegram destination · Optional posting destination for cleaned media
- **Signatures JSON**: persistent state · Stored signatures and saved settings

## Connections

- bot.py → Main loop: starts · Local launcher hands off to the bot bootstrapper
- Entrypoint → Main loop: runs · Container entrypoint launches the same application path
- Compose → Entrypoint: invokes · Compose starts the container command
- Dockerfile → Requirements: installs · Image build pulls in Python dependencies
- Main loop → Config: loads · Bootstrap reads runtime settings and secrets
- Main loop → Handlers: registers · Wires update handlers into the application
- Handlers → Keyboards: uses · Builds conversational UI and quick actions
- Handlers → Utils: delegates · Uses shared media and caption processing helpers
- Handlers → Storage: reads/writes · Loads and persists signatures or settings
- Storage → Signatures JSON: persists · File-backed durable state for signatures
- Main loop → Telegram API: connects · Bot runtime communicates with Telegram
- Telegram API → Handlers: delivers updates · Incoming messages and commands enter the handler layer
- Handlers → Operator: checks access · Restricts control to the configured operator
- Handlers → Channel: posts to · Optional output path for cleaned media
- Config → Operator: defines · Configured user ID comes from environment
- Config → Channel: defines · Optional channel destination comes from environment
- Config → Signatures JSON: defines · Environment can override signature storage path
- Env example → Config: documents · Example variables mirror the configuration boundary
