# nodirbek-ai/movie-recommender-ai architecture

> Architecture diagram of the GitHub repository nodirbek-ai/movie-recommender-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nodirbek-ai/movie-recommender-ai
- Repository: https://github.com/nodirbek-ai/movie-recommender-ai

## Overview

This is a command-line movie recommender. Its data-preparation workflow fetches popular movie metadata from TMDB, saves a local catalog, and builds text embeddings; the CLI loads those embeddings and supports natural-language search and finding films similar to a title. The graph separates catalog ingestion, embedding preparation, and interactive recommendation. Source excerpts show these stages and their file-based handoffs; the README is empty, so no further documented capabilities are available.

Main entry points: [`src/build_embeddings.py`](https://github.com/nodirbek-ai/movie-recommender-ai/blob/main/src/build_embeddings.py) (Embedding builder), [`src/recommender.py`](https://github.com/nodirbek-ai/movie-recommender-ai/blob/main/src/recommender.py) (Recommendation engine), [`src/fetch_movies.py`](https://github.com/nodirbek-ai/movie-recommender-ai/blob/main/src/fetch_movies.py) (Movie fetcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Catalog ingestion"]
  node_catalog[("Movie catalog<br/>[fetch_movies.py]")]
  node_fetcher["Movie fetcher<br/>[fetch_movies.py]"]
end

subgraph group_embeddings["Embedding preparation"]
  node_builder["Embedding builder"]
  node_embedding_store[("Embedding data")]
end

subgraph group_recommend["Interactive recommendations"]
  node_cli["Menu interface<br/>[recommender.py]"]
  node_engine["Recommendation engine<br/>[recommender.py]"]
end

node_user(("CLI user"))
node_tmdb["TMDB API"]
node_encoder["Sentence Transformer"]

node_user -->|"uses"| node_cli
node_cli -->|"queries"| node_engine
node_fetcher -->|"fetches popular films"| node_tmdb
node_fetcher -->|"writes JSON"| node_catalog
node_builder -->|"reads JSON"| node_catalog
node_builder -->|"encodes film text"| node_encoder
node_builder -->|"writes JSON"| node_embedding_store
node_engine -->|"loads vectors"| node_embedding_store
node_engine -->|"embeds query"| node_encoder

click node_cli "https://github.com/nodirbek-ai/movie-recommender-ai/blob/main/src/recommender.py"
click node_engine "https://github.com/nodirbek-ai/movie-recommender-ai/blob/main/src/recommender.py"
click node_catalog "https://github.com/nodirbek-ai/movie-recommender-ai/blob/main/src/fetch_movies.py"
click node_fetcher "https://github.com/nodirbek-ai/movie-recommender-ai/blob/main/src/fetch_movies.py"
click node_builder "https://github.com/nodirbek-ai/movie-recommender-ai/blob/main/src/build_embeddings.py"
click node_embedding_store "https://github.com/nodirbek-ai/movie-recommender-ai/blob/main/src/build_embeddings.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_catalog,node_fetcher,node_user toneBlue
class node_builder,node_embedding_store toneAmber
class node_cli,node_engine,node_tmdb toneMint
class node_encoder toneIndigo
```

## Components

### Catalog ingestion

- [Movie catalog](https://github.com/nodirbek-ai/movie-recommender-ai/blob/main/src/fetch_movies.py): `src/fetch_movies.py`
- [Movie fetcher](https://github.com/nodirbek-ai/movie-recommender-ai/blob/main/src/fetch_movies.py): `src/fetch_movies.py`

### Embedding preparation

- [Embedding builder](https://github.com/nodirbek-ai/movie-recommender-ai/blob/main/src/build_embeddings.py): `src/build_embeddings.py`
- [Embedding data](https://github.com/nodirbek-ai/movie-recommender-ai/blob/main/src/build_embeddings.py): `src/build_embeddings.py`

### Interactive recommendations

- [Menu interface](https://github.com/nodirbek-ai/movie-recommender-ai/blob/main/src/recommender.py): `src/recommender.py`
- [Recommendation engine](https://github.com/nodirbek-ai/movie-recommender-ai/blob/main/src/recommender.py): `src/recommender.py`

### Other components

- **CLI user**
- **TMDB API**
- **Sentence Transformer**

## Connections

- CLI user → Menu interface: uses (evidence: `src/recommender.py`)
- Menu interface → Recommendation engine: queries (evidence: `src/recommender.py`)
- Movie fetcher → TMDB API: fetches popular films (evidence: `src/fetch_movies.py`)
- Movie fetcher → Movie catalog: writes JSON (evidence: `src/fetch_movies.py`)
- Embedding builder → Movie catalog: reads JSON (evidence: `src/build_embeddings.py`)
- Embedding builder → Sentence Transformer: encodes film text (evidence: `src/build_embeddings.py`)
- Embedding builder → Embedding data: writes JSON (evidence: `src/build_embeddings.py`)
- Recommendation engine → Embedding data: loads vectors (evidence: `src/recommender.py`)
- Recommendation engine → Sentence Transformer: embeds query (evidence: `src/recommender.py`)
