# kkleytt/cinema-bot architecture

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

## Overview

This repository is a Russian-language Telegram film-discovery bot, with a desktop film-data entry/parser tool alongside it. The main workflow is a Telegram user choosing a search or recommendation criterion, receiving film details and viewing links, then optionally saving or marking a film as watched. The README also describes favorites, filtering, and a continuing random-selection feed. Bot handlers and SQLite access are concentrated in bot/main.py; misc/misc.py provides database setup and search helpers. The desktop tool’s parsing flow is visible, but its relationship to the bot’s runtime catalog is not established by the excerpts.

Main entry points: [`bot/main.py`](https://github.com/kkleytt/cinema-bot/blob/main/bot/main.py) (Bot runtime), [`keyboards/kb.py`](https://github.com/kkleytt/cinema-bot/blob/main/keyboards/kb.py) (Inline menus), [`parser/prs.py`](https://github.com/kkleytt/cinema-bot/blob/main/parser/prs.py) (Metadata parser), [`misc/misc.py`](https://github.com/kkleytt/cinema-bot/blob/main/misc/misc.py) (Film catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telegram["Telegram experience"]
  node_bot["Bot runtime<br/>[main.py]"]
  node_menus["Inline menus<br/>[kb.py]"]
  node_text["Bot copy<br/>[text_bot.py]"]
  node_search["Film search<br/>[main.py]"]
  node_recommend["Film recommendations<br/>[main.py]"]
  node_filter["Catalog filtering<br/>[main.py]"]
  node_filmview["Film details<br/>[main.py]"]
  node_links["Viewing links<br/>[main.py]"]
  node_favorites["Favorites<br/>[main.py]"]
  node_watched["Viewing history<br/>[main.py]"]
  node_profiledb[("User records<br/>[misc.py]")]
  node_catalogdb[("Film catalog<br/>[misc.py]")]
end

subgraph group_catalog["Film catalog tools"]
  node_desktop["Catalog editor<br/>[app.py]"]
  node_metadata["Metadata parser<br/>[prs.py]"]
  node_listparser["Link-list parser<br/>[parser.py]"]
  node_datawriter["Catalog generation<br/>[generate.py]"]
end

subgraph group_support["Shared bot support"]
  node_helpers["Search helpers<br/>[misc.py]"]
end

node_user(("Telegram user"))
node_external{{"Film information services"}}

node_user -->|"interacts with"| node_bot
node_bot -->|"uses menus"| node_menus
node_menus -->|"uses labels"| node_text
node_bot -->|"handles search"| node_search
node_bot -->|"offers selection"| node_recommend
node_bot -->|"filters films"| node_filter
node_bot -->|"shows details"| node_filmview
node_bot -->|"provides links"| node_links
node_bot -->|"saves favorites"| node_favorites
node_bot -->|"tracks watched"| node_watched
node_bot -->|"writes user data"| node_profiledb
node_bot -->|"reads film data"| node_catalogdb
node_bot -.->|"uses search helpers"| node_helpers
node_desktop -->|"parses metadata"| node_metadata
node_metadata -->|"requests film data"| node_external
node_listparser -->|"checks existing links"| node_catalogdb
node_datawriter -->|"fetches metadata"| node_external

click node_bot "https://github.com/kkleytt/cinema-bot/blob/main/bot/main.py"
click node_menus "https://github.com/kkleytt/cinema-bot/blob/main/keyboards/kb.py"
click node_text "https://github.com/kkleytt/cinema-bot/blob/main/textbot/text_bot.py"
click node_search "https://github.com/kkleytt/cinema-bot/blob/main/bot/main.py"
click node_recommend "https://github.com/kkleytt/cinema-bot/blob/main/bot/main.py"
click node_filter "https://github.com/kkleytt/cinema-bot/blob/main/bot/main.py"
click node_filmview "https://github.com/kkleytt/cinema-bot/blob/main/bot/main.py"
click node_links "https://github.com/kkleytt/cinema-bot/blob/main/bot/main.py"
click node_favorites "https://github.com/kkleytt/cinema-bot/blob/main/bot/main.py"
click node_watched "https://github.com/kkleytt/cinema-bot/blob/main/bot/main.py"
click node_profiledb "https://github.com/kkleytt/cinema-bot/blob/main/misc/misc.py"
click node_catalogdb "https://github.com/kkleytt/cinema-bot/blob/main/misc/misc.py"
click node_desktop "https://github.com/kkleytt/cinema-bot/blob/main/parser/app.py"
click node_metadata "https://github.com/kkleytt/cinema-bot/blob/main/parser/prs.py"
click node_listparser "https://github.com/kkleytt/cinema-bot/blob/main/parser/parser.py"
click node_datawriter "https://github.com/kkleytt/cinema-bot/blob/main/parser/generate.py"
click node_helpers "https://github.com/kkleytt/cinema-bot/blob/main/misc/misc.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_menus,node_text,node_search,node_recommend,node_filter,node_filmview,node_links,node_favorites,node_watched,node_profiledb,node_catalogdb,node_user toneBlue
class node_desktop,node_metadata,node_listparser,node_datawriter toneAmber
class node_helpers toneMint
class node_external toneIndigo
```

## Components

### Telegram experience

- [Bot runtime](https://github.com/kkleytt/cinema-bot/blob/main/bot/main.py): `bot/main.py`
- [Inline menus](https://github.com/kkleytt/cinema-bot/blob/main/keyboards/kb.py): `keyboards/kb.py`
- [Bot copy](https://github.com/kkleytt/cinema-bot/blob/main/textbot/text_bot.py): `textbot/text_bot.py`
- [Film search](https://github.com/kkleytt/cinema-bot/blob/main/bot/main.py): `bot/main.py`
- [Film recommendations](https://github.com/kkleytt/cinema-bot/blob/main/bot/main.py): `bot/main.py`
- [Catalog filtering](https://github.com/kkleytt/cinema-bot/blob/main/bot/main.py): `bot/main.py`
- [Film details](https://github.com/kkleytt/cinema-bot/blob/main/bot/main.py): `bot/main.py`
- [Viewing links](https://github.com/kkleytt/cinema-bot/blob/main/bot/main.py): `bot/main.py`
- [Favorites](https://github.com/kkleytt/cinema-bot/blob/main/bot/main.py): `bot/main.py`
- [Viewing history](https://github.com/kkleytt/cinema-bot/blob/main/bot/main.py): `bot/main.py`
- [User records](https://github.com/kkleytt/cinema-bot/blob/main/misc/misc.py): `misc/misc.py`
- [Film catalog](https://github.com/kkleytt/cinema-bot/blob/main/misc/misc.py): `misc/misc.py`

### Film catalog tools

- [Catalog editor](https://github.com/kkleytt/cinema-bot/blob/main/parser/app.py): `parser/app.py`
- [Metadata parser](https://github.com/kkleytt/cinema-bot/blob/main/parser/prs.py): `parser/prs.py`
- [Link-list parser](https://github.com/kkleytt/cinema-bot/blob/main/parser/parser.py): `parser/parser.py`
- [Catalog generation](https://github.com/kkleytt/cinema-bot/blob/main/parser/generate.py): `parser/generate.py`

### Shared bot support

- [Search helpers](https://github.com/kkleytt/cinema-bot/blob/main/misc/misc.py): `misc/misc.py`

### Other components

- **Telegram user**
- **Film information services**

## Connections

- Telegram user → Bot runtime: interacts with (evidence: `README.md`)
- Bot runtime → Inline menus: uses menus (evidence: `bot/main.py`)
- Inline menus → Bot copy: uses labels (evidence: `keyboards/kb.py`)
- Bot runtime → Film search: handles search (evidence: `README.md`)
- Bot runtime → Film recommendations: offers selection (evidence: `README.md`)
- Bot runtime → Catalog filtering: filters films (evidence: `README.md`)
- Bot runtime → Film details: shows details (evidence: `bot/main.py`)
- Bot runtime → Viewing links: provides links (evidence: `README.md`)
- Bot runtime → Favorites: saves favorites (evidence: `README.md`)
- Bot runtime → Viewing history: tracks watched (evidence: `README.md`)
- Bot runtime → User records: writes user data (evidence: `bot/main.py`)
- Bot runtime → Film catalog: reads film data (evidence: `misc/misc.py`)
- Bot runtime → Search helpers: uses search helpers (evidence: `bot/main.py`)
- Catalog editor → Metadata parser: parses metadata (evidence: `parser/app.py`)
- Metadata parser → Film information services: requests film data (evidence: `parser/prs.py`)
- Link-list parser → Film catalog: checks existing links (evidence: `parser/parser.py`)
- Catalog generation → Film information services: fetches metadata (evidence: `parser/generate.py`)
