# arkaim/moviebot architecture

> Architecture diagram of the GitHub repository arkaim/moviebot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arkaim/moviebot
- Repository: https://github.com/arkaim/moviebot

## Overview

This repository implements a Telegram movie bot. Users can search for movie details, look up a person and notable credits, or discover popular movies by choosing a genre and then a numbered result. The main workflow is implemented in `src/kpapi.js`; `src/options.js` supplies the inline keyboards used in genre discovery and result selection. The tree does not include the token module required by the bot, and `src/genres.js` is not referenced by the sampled bot code, so neither is shown as an active runtime dependency.

Main entry points: [`src/kpapi.js`](https://github.com/arkaim/moviebot/blob/master/src/kpapi.js) (Bot command handlers), [`src/options.js`](https://github.com/arkaim/moviebot/blob/master/src/options.js) (Inline keyboards)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telegram["Telegram interface"]
  node_bot["Bot command handlers<br/>[kpapi.js]"]
  node_keyboards["Inline keyboards<br/>[options.js]"]
end

subgraph group_movie["Movie discovery"]
  node_movie_search["Movie search<br/>[kpapi.js]"]
  node_movie_details["Movie details<br/>[kpapi.js]"]
  node_person_search["Person search<br/>[kpapi.js]"]
  node_genre_discovery["Genre discovery<br/>[kpapi.js]"]
  node_result_selection["Result selection<br/>[kpapi.js]"]
end

subgraph group_integration["External services"]
  node_telegram_api["Telegram Bot API"]
  node_tmdb["The Movie Database"]
end

node_user(("Telegram user"))

node_user -->|"sends commands"| node_telegram_api
node_telegram_api -->|"dispatches updates"| node_bot
node_bot -->|"handles /movie"| node_movie_search
node_bot -->|"handles /cast"| node_person_search
node_bot -->|"handles /genre"| node_genre_discovery
node_genre_discovery -->|"uses genre keys"| node_keyboards
node_genre_discovery -->|"requests discovery"| node_tmdb
node_tmdb -->|"returns movie list"| node_genre_discovery
node_genre_discovery -->|"sends list and numbers"| node_telegram_api
node_telegram_api -->|"dispatches selection"| node_bot
node_bot -->|"handles callback"| node_result_selection
node_result_selection -->|"uses number keys"| node_keyboards
node_result_selection -->|"searches selected title"| node_movie_search
node_movie_search -->|"searches movies"| node_tmdb
node_tmdb -->|"returns matches"| node_movie_search
node_movie_search -->|"requests selected movie"| node_movie_details
node_movie_details -->|"fetches movie info"| node_tmdb
node_tmdb -->|"returns details"| node_movie_details
node_movie_details -->|"sends movie details"| node_telegram_api
node_movie_search -->|"sends no-match reply"| node_telegram_api
node_person_search -->|"searches people"| node_tmdb
node_tmdb -->|"returns person credits"| node_person_search
node_person_search -->|"sends profile and credits"| node_telegram_api
node_person_search -->|"sends no-match reply"| node_telegram_api
node_genre_discovery -->|"prompts genre choice"| node_telegram_api
node_telegram_api -->|"sends replies"| node_user

click node_bot "https://github.com/arkaim/moviebot/blob/master/src/kpapi.js"
click node_keyboards "https://github.com/arkaim/moviebot/blob/master/src/options.js"
click node_movie_search "https://github.com/arkaim/moviebot/blob/master/src/kpapi.js"
click node_movie_details "https://github.com/arkaim/moviebot/blob/master/src/kpapi.js"
click node_person_search "https://github.com/arkaim/moviebot/blob/master/src/kpapi.js"
click node_genre_discovery "https://github.com/arkaim/moviebot/blob/master/src/kpapi.js"
click node_result_selection "https://github.com/arkaim/moviebot/blob/master/src/kpapi.js"

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_keyboards,node_user toneBlue
class node_movie_search,node_movie_details,node_person_search,node_genre_discovery,node_result_selection toneAmber
class node_telegram_api,node_tmdb toneMint
```

## Components

### Telegram interface

- [Bot command handlers](https://github.com/arkaim/moviebot/blob/master/src/kpapi.js): `src/kpapi.js`
- [Inline keyboards](https://github.com/arkaim/moviebot/blob/master/src/options.js): `src/options.js`

### Movie discovery

- [Movie search](https://github.com/arkaim/moviebot/blob/master/src/kpapi.js): `src/kpapi.js`
- [Movie details](https://github.com/arkaim/moviebot/blob/master/src/kpapi.js): `src/kpapi.js`
- [Person search](https://github.com/arkaim/moviebot/blob/master/src/kpapi.js): `src/kpapi.js`
- [Genre discovery](https://github.com/arkaim/moviebot/blob/master/src/kpapi.js): `src/kpapi.js`
- [Result selection](https://github.com/arkaim/moviebot/blob/master/src/kpapi.js): `src/kpapi.js`

### External services

- **Telegram Bot API**
- **The Movie Database**

### Other components

- **Telegram user**

## Connections

- Telegram user → Telegram Bot API: sends commands
- Telegram Bot API → Bot command handlers: dispatches updates
- Bot command handlers → Movie search: handles /movie
- Bot command handlers → Person search: handles /cast
- Bot command handlers → Genre discovery: handles /genre
- Genre discovery → Inline keyboards: uses genre keys
- Genre discovery → The Movie Database: requests discovery
- The Movie Database → Genre discovery: returns movie list
- Genre discovery → Telegram Bot API: sends list and numbers
- Telegram Bot API → Bot command handlers: dispatches selection
- Bot command handlers → Result selection: handles callback
- Result selection → Inline keyboards: uses number keys
- Result selection → Movie search: searches selected title
- Movie search → The Movie Database: searches movies
- The Movie Database → Movie search: returns matches
- Movie search → Movie details: requests selected movie
- Movie details → The Movie Database: fetches movie info
- The Movie Database → Movie details: returns details
- Movie details → Telegram Bot API: sends movie details
- Movie search → Telegram Bot API: sends no-match reply
- Person search → The Movie Database: searches people
- The Movie Database → Person search: returns person credits
- Person search → Telegram Bot API: sends profile and credits
- Person search → Telegram Bot API: sends no-match reply
- Genre discovery → Telegram Bot API: prompts genre choice
- Telegram Bot API → Telegram user: sends replies