# thenightlygod/lukidown_bot architecture

> Architecture diagram of the GitHub repository thenightlygod/lukidown_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/thenightlygod/lukidown_bot
- Repository: https://github.com/thenightlygod/lukidown_bot

## Overview

lukidown is a Telegram media-downloading bot. Users submit links or search queries, choose a format or quality, and receive downloaded media; Kinopoisk adds a browse-and-select flow. The bot coordinates platform detection, download routing, task services, and Telegram interactions. Major documented capabilities also include inline queries, music-search fallback, caching/history, cancellation, localization, and health checks. Some runtime wiring is only documented or appears in the source index, so uncertain relationships are omitted or marked unverified.

Main entry points: [`bot.py`](https://github.com/thenightlygod/lukidown_bot/blob/latest/bot.py) (Bot handlers), [`downloaders/router.py`](https://github.com/thenightlygod/lukidown_bot/blob/latest/downloaders/router.py) (Download router), [`downloaders/core.py`](https://github.com/thenightlygod/lukidown_bot/blob/latest/downloaders/core.py) (Media engine), [`downloaders/kinopoisk.py`](https://github.com/thenightlygod/lukidown_bot/blob/latest/downloaders/kinopoisk.py) (Kinopoisk browsing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Bot interaction"]
  node_bot["Bot handlers<br/>[bot.py]"]
  node_platforms["Platform detection<br/>[platforms.py]"]
  node_localization["Translations<br/>[i18n.py]"]
end

subgraph group_downloads["Download processing"]
  node_router["Download router<br/>[router.py]"]
  node_core["Media engine<br/>[core.py]"]
  node_collections["Collection downloads<br/>[collections.py]"]
  node_kinopoisk["Kinopoisk browsing<br/>[kinopoisk.py]"]
  node_music["Music handlers"]
  node_transcoder["Media transcoder<br/>[transcoder.py]"]
end

subgraph group_state["Tasks and storage"]
  node_services["Task and history services<br/>[services.py]"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
end

subgraph group_runtime["Runtime support"]
  node_http["HTTP clients<br/>[http.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_health["Health server<br/>[health.py]"]
end

node_user(("Telegram user"))
node_telegram["Telegram"]
node_orchestrator["Container orchestrator"]

node_user -->|"sends requests"| node_bot
node_bot -->|"replies with media"| node_telegram
node_bot -->|"detects links"| node_platforms
node_bot -->|"requests downloads"| node_router
node_router -->|"routes by platform"| node_platforms
node_router -->|"downloads media"| node_core
node_router -->|"downloads collections"| node_collections
node_router -->|"dispatches requests"| node_kinopoisk
node_router -->|"dispatches requests"| node_music
node_router -->|"compresses media"| node_transcoder
node_kinopoisk -->|"uses download engine"| node_core
node_kinopoisk -->|"fetches service data"| node_http
node_core -.->|"uses HTTP clients"| node_http
node_music -.->|"uses download engine"| node_core
node_music -.->|"fetches platform data"| node_http
node_bot -->|"manages tasks and history"| node_services
node_services -->|"reads and writes"| node_postgres
node_services -->|"queues and cancels"| node_redis
node_bot -->|"renders localized text"| node_localization
node_bot -->|"starts health server"| node_health
node_orchestrator -->|"checks health"| node_health
node_config -.->|"configures runtime"| node_bot

click node_bot "https://github.com/thenightlygod/lukidown_bot/blob/latest/bot.py"
click node_platforms "https://github.com/thenightlygod/lukidown_bot/blob/latest/platforms.py"
click node_localization "https://github.com/thenightlygod/lukidown_bot/blob/latest/i18n.py"
click node_router "https://github.com/thenightlygod/lukidown_bot/blob/latest/downloaders/router.py"
click node_core "https://github.com/thenightlygod/lukidown_bot/blob/latest/downloaders/core.py"
click node_collections "https://github.com/thenightlygod/lukidown_bot/blob/latest/downloaders/collections.py"
click node_kinopoisk "https://github.com/thenightlygod/lukidown_bot/blob/latest/downloaders/kinopoisk.py"
click node_music "https://github.com/thenightlygod/lukidown_bot/tree/latest/downloaders"
click node_http "https://github.com/thenightlygod/lukidown_bot/blob/latest/downloaders/http.py"
click node_transcoder "https://github.com/thenightlygod/lukidown_bot/blob/latest/downloaders/transcoder.py"
click node_services "https://github.com/thenightlygod/lukidown_bot/blob/latest/services.py"
click node_config "https://github.com/thenightlygod/lukidown_bot/blob/latest/config.py"
click node_health "https://github.com/thenightlygod/lukidown_bot/blob/latest/health.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,node_platforms,node_localization,node_user toneBlue
class node_router,node_core,node_collections,node_kinopoisk,node_music,node_transcoder toneAmber
class node_services,node_postgres,node_redis toneMint
class node_http,node_config,node_health toneRose
class node_telegram,node_orchestrator toneIndigo
```

## Components

### Bot interaction

- [Bot handlers](https://github.com/thenightlygod/lukidown_bot/blob/latest/bot.py): `bot.py`
- [Platform detection](https://github.com/thenightlygod/lukidown_bot/blob/latest/platforms.py): `platforms.py`
- [Translations](https://github.com/thenightlygod/lukidown_bot/blob/latest/i18n.py): `i18n.py`

### Download processing

- [Download router](https://github.com/thenightlygod/lukidown_bot/blob/latest/downloaders/router.py): `downloaders/router.py`
- [Media engine](https://github.com/thenightlygod/lukidown_bot/blob/latest/downloaders/core.py): `downloaders/core.py`
- [Collection downloads](https://github.com/thenightlygod/lukidown_bot/blob/latest/downloaders/collections.py): `downloaders/collections.py`
- [Kinopoisk browsing](https://github.com/thenightlygod/lukidown_bot/blob/latest/downloaders/kinopoisk.py): `downloaders/kinopoisk.py`
- [Music handlers](https://github.com/thenightlygod/lukidown_bot/tree/latest/downloaders): `downloaders`
- [Media transcoder](https://github.com/thenightlygod/lukidown_bot/blob/latest/downloaders/transcoder.py): `downloaders/transcoder.py`

### Tasks and storage

- [Task and history services](https://github.com/thenightlygod/lukidown_bot/blob/latest/services.py): `services.py`
- **PostgreSQL**
- **Redis**

### Runtime support

- [HTTP clients](https://github.com/thenightlygod/lukidown_bot/blob/latest/downloaders/http.py): `downloaders/http.py`
- [Configuration](https://github.com/thenightlygod/lukidown_bot/blob/latest/config.py): `config.py`
- [Health server](https://github.com/thenightlygod/lukidown_bot/blob/latest/health.py): `health.py`

### Other components

- **Telegram user**
- **Telegram**
- **Container orchestrator**

## Connections

- Telegram user → Bot handlers: sends requests (evidence: `README.md`)
- Bot handlers → Telegram: replies with media (evidence: `README.md`)
- Bot handlers → Platform detection: detects links (evidence: `bot.py`)
- Bot handlers → Download router: requests downloads (evidence: `README.md`)
- Download router → Platform detection: routes by platform (evidence: `downloaders/router.py`)
- Download router → Media engine: downloads media (evidence: `downloaders/router.py`)
- Download router → Collection downloads: downloads collections (evidence: `downloaders/router.py`)
- Download router → Kinopoisk browsing: dispatches requests (evidence: `downloaders/router.py`)
- Download router → Music handlers: dispatches requests (evidence: `downloaders/router.py`)
- Download router → Media transcoder: compresses media (evidence: `downloaders/router.py`)
- Kinopoisk browsing → Media engine: uses download engine (evidence: `downloaders/kinopoisk.py`)
- Kinopoisk browsing → HTTP clients: fetches service data (evidence: `downloaders/kinopoisk.py`)
- Media engine → HTTP clients: uses HTTP clients (evidence: `downloaders/core.py`)
- Music handlers → Media engine: uses download engine (evidence: `downloaders/router.py`)
- Music handlers → HTTP clients: fetches platform data (evidence: `downloaders/core.py`)
- Bot handlers → Task and history services: manages tasks and history (evidence: `bot.py`)
- Task and history services → PostgreSQL: reads and writes (evidence: `services.py`)
- Task and history services → Redis: queues and cancels (evidence: `services.py`)
- Bot handlers → Translations: renders localized text (evidence: `bot.py`)
- Bot handlers → Health server: starts health server (evidence: `bot.py`)
- Container orchestrator → Health server: checks health (evidence: `README.md`)
- Configuration → Bot handlers: configures runtime (evidence: `bot.py`)
