# ankit5641/movie-recommend-system architecture

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

- Interactive diagram: https://gitdiagram.com/ankit5641/movie-recommend-system
- Repository: https://github.com/ankit5641/movie-recommend-system

## Overview

1. **Overall shape**
   - This repo is a small two-stage recommendation system: an **offline data/preprocessing stage** and an **online Streamlit inference UI**.
   - The runtime app does not train a model; it consumes **precomputed artifacts** produced from TMDB movie data.

2. **Primary runtime entrypoint**
   - `app.py` is the main application entrypoint for the deployed experience.
   - The README’s local run instructions use `streamlit run app.py`, so this is the user-facing boundary where requests start and results are rendered.

3. **Interactive UI layer**
   - The frontend is built with **Streamlit**.
   - Its job is to let a user pick a movie, trigger a recommendation lookup, and display results as movie cards/posters.

4. **Recommendation engine boundary**
   - The core ML logic is **content-based filtering**.
   - Instead of calling a live model service, the app reads a **precomputed similarity matrix** from `similarity.pkl` and uses it to rank movies similar to the selected title.

5. **Movie metadata store**
   - `movie_dict.pkl` and `movies.pkl` are serialized data artifacts used by the app.
   - These likely hold the normalized movie catalog and lookup-friendly structures needed to map a title selection into an internal movie index and metadata for display.

6. **Offline data preparation**
   - The raw sources are `tmdb_5000_movies.csv` and `tmdb_5000_credits.csv`.
   - The notebook `Movie recommender system.ipynb` is the offline workspace where the CSVs were cleaned, feature-engineered, vectorized, and converted into the persisted `.pkl` artifacts.

7. **Data flow at runtime**
   - User selects a movie in Streamlit.
   - The app looks up that movie in the serialized movie dictionary.
   - It reads the corresponding row from the similarity matrix, finds the nearest matches, and returns the top recommendations.
   - For each recommended title, the app fetches poster imagery from the external TMDB service.

8. **External integration**
   - The only clear external runtime dependency beyond Python packages is the **TMDB API**.
   - TMDB is used for **poster enrichment**, not for recommendation scoring, which keeps the recommender fast and deterministic while still producing rich UI output.

9. **Persistence and deployment model**
   - There is no database, queue, or backend service layer in this repo.
   - Persistence is file-based through pickle artifacts checked into the repository, which makes the deployment simple and Streamlit-friendly.

10. **Supporting scripts**
   - `main.py` is present as an additional Python entrypoint, but the README and structure indicate `app.py` is the canonical app path.
   - If you’re drawing the architecture, treat `main.py` as auxiliary unless its contents show otherwise.

11. **Technology stack**
   - Core stack: **Python 3.9**, **Streamlit**, **Pandas**, and **Pickle** serialization.
   - ML is implemented as lightweight offline feature engineering plus similarity computation, rather than a model-serving framework.

12. **Key architectural boundary to diagram**
   - The most important split is between:
     - **offline artifact generation** from TMDB CSV data, and
     - **online recommendation serving** from precomputed pickle files plus live TMDB poster lookup.
   - That boundary is what makes the app responsive and easy to deploy on Streamlit Cloud.

Main entry points: [`Movie recommender system.ipynb`](https://github.com/ankit5641/movie-recommend-system/blob/HEAD/Movie%20recommender%20system.ipynb) (Notebook), [`movies.pkl`](https://github.com/ankit5641/movie-recommend-system/blob/main/movies.pkl) (Movies data), [`movie_dict.pkl`](https://github.com/ankit5641/movie-recommend-system/blob/main/movie_dict.pkl) (Movie map), [`similarity.pkl`](https://github.com/ankit5641/movie-recommend-system/blob/main/similarity.pkl) (Similarity matrix)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_offline["Offline prep"]
  node_notebook["Notebook<br/>offline pipeline"]
  node_tmdb_movies["Movies CSV<br/>raw data"]
  node_tmdb_credits["Credits CSV<br/>raw data"]
  node_movies_pkl["Movies data<br/>serialized catalog<br/>[movies.pkl]"]
  node_movie_dict_pkl["Movie map<br/>serialized lookup<br/>[movie_dict.pkl]"]
  node_similarity_pkl["Similarity matrix<br/>precomputed ranking<br/>[similarity.pkl]"]
end

subgraph group_online["Online app"]
  node_app_py["App entry<br/>streamlit app<br/>[app.py]"]
  node_streamlit_ui["Movie UI<br/>interactive frontend"]
  node_reco_engine{{"Recommender<br/>content-based core"}}
  node_poster_fetch(("Poster lookup<br/>tmdb integration"))
  node_main_py["Main entry<br/>auxiliary entrypoint<br/>[main.py]"]
end

node_tmdb_api(("TMDB API<br/>external service"))

node_tmdb_movies -->|"inputs"| node_notebook
node_tmdb_credits -->|"inputs"| node_notebook
node_notebook -->|"produces"| node_movies_pkl
node_notebook -->|"produces"| node_movie_dict_pkl
node_notebook -->|"produces"| node_similarity_pkl
node_app_py -->|"renders"| node_streamlit_ui
node_streamlit_ui -->|"triggers"| node_reco_engine
node_reco_engine -->|"reads"| node_movie_dict_pkl
node_reco_engine -->|"reads"| node_movies_pkl
node_reco_engine -->|"reads"| node_similarity_pkl
node_reco_engine -->|"enriches"| node_poster_fetch
node_poster_fetch -->|"calls"| node_tmdb_api
node_poster_fetch -->|"returns"| node_streamlit_ui
node_main_py -.->|"alt entry"| node_streamlit_ui

click node_notebook "https://github.com/ankit5641/movie-recommend-system/blob/main/Movie recommender system.ipynb"
click node_tmdb_movies "https://github.com/ankit5641/movie-recommend-system/blob/main/tmdb_5000_movies.csv"
click node_tmdb_credits "https://github.com/ankit5641/movie-recommend-system/blob/main/tmdb_5000_credits.csv"
click node_movies_pkl "https://github.com/ankit5641/movie-recommend-system/blob/main/movies.pkl"
click node_movie_dict_pkl "https://github.com/ankit5641/movie-recommend-system/blob/main/movie_dict.pkl"
click node_similarity_pkl "https://github.com/ankit5641/movie-recommend-system/blob/main/similarity.pkl"
click node_app_py "https://github.com/ankit5641/movie-recommend-system/blob/main/app.py"
click node_main_py "https://github.com/ankit5641/movie-recommend-system/blob/main/main.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_notebook,node_tmdb_movies,node_tmdb_credits,node_movies_pkl,node_movie_dict_pkl,node_similarity_pkl toneBlue
class node_app_py,node_streamlit_ui,node_reco_engine,node_poster_fetch,node_main_py toneAmber
class node_tmdb_api toneNeutral
```

## Components

### Offline prep

Builds the serialized recommendation artifacts from raw TMDB data.

- [Notebook](https://github.com/ankit5641/movie-recommend-system/blob/HEAD/Movie%20recommender%20system.ipynb): offline pipeline · Exploratory workspace that cleans TMDB data, engineers features, and generates artifacts. · `Movie recommender system.ipynb`
- [Movies CSV](https://github.com/ankit5641/movie-recommend-system/blob/main/tmdb_5000_movies.csv): raw data · Raw TMDB movie metadata source used during offline preparation. · `tmdb_5000_movies.csv`
- [Credits CSV](https://github.com/ankit5641/movie-recommend-system/blob/main/tmdb_5000_credits.csv): raw data · Raw TMDB cast and crew source used during offline preparation. · `tmdb_5000_credits.csv`
- [Movies data](https://github.com/ankit5641/movie-recommend-system/blob/main/movies.pkl): serialized catalog · Normalized movie catalog and lookup-friendly records consumed by the app. · `movies.pkl`
- [Movie map](https://github.com/ankit5641/movie-recommend-system/blob/main/movie_dict.pkl): serialized lookup · Dictionary-like structure for mapping titles to internal movie indices and metadata. · `movie_dict.pkl`
- [Similarity matrix](https://github.com/ankit5641/movie-recommend-system/blob/main/similarity.pkl): precomputed ranking · Precomputed content-similarity scores used to find nearest movie matches. · `similarity.pkl`

### Online app

Serves interactive movie recommendations in Streamlit using precomputed artifacts.

- [App entry](https://github.com/ankit5641/movie-recommend-system/blob/main/app.py): streamlit app · Primary runtime entrypoint for the deployed recommendation experience. · `app.py`
- **Movie UI**: interactive frontend · Lets users pick a movie and displays recommended titles as cards or posters.
- **Recommender**: content-based core · Loads the movie lookup data and similarity matrix, then ranks nearest movies for the selected title.
- **Poster lookup**: tmdb integration · Fetches poster imagery from TMDB for recommended titles.
- [Main entry](https://github.com/ankit5641/movie-recommend-system/blob/main/main.py): auxiliary entrypoint · Secondary Python entrypoint present in the repo, but not the documented deployment path. · `main.py`

### Other components

- **TMDB API**: external service · External API used only for poster enrichment at runtime.

## Connections

- Movies CSV → Notebook: inputs · Raw movie metadata is processed in the offline notebook.
- Credits CSV → Notebook: inputs · Raw credit data is joined and transformed offline.
- Notebook → Movies data: produces · Offline preprocessing writes the normalized movie catalog.
- Notebook → Movie map: produces · Offline preprocessing writes lookup structures for title selection.
- Notebook → Similarity matrix: produces · Offline feature engineering computes the similarity matrix.
- App entry → Movie UI: renders · The Streamlit entrypoint serves the interactive interface.
- Movie UI → Recommender: triggers · User selection initiates recommendation lookup.
- Recommender → Movie map: reads · The engine resolves titles to movie indices and metadata.
- Recommender → Movies data: reads · The engine uses the catalog for recommendation display data.
- Recommender → Similarity matrix: reads · The engine ranks candidates using the precomputed similarity scores.
- Recommender → Poster lookup: enriches · Recommended titles are passed for poster enrichment.
- Poster lookup → TMDB API: calls · Poster imagery is fetched from TMDB at runtime.
- Poster lookup → Movie UI: returns · Poster URLs or images are returned for display.
- Main entry → Movie UI: alt entry · Auxiliary entrypoint that may also launch or proxy the app.
