# aayush-0409/movie-recommender-system architecture

> Architecture diagram of the GitHub repository aayush-0409/movie-recommender-system, 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/aayush-0409/movie-recommender-system
- Repository: https://github.com/aayush-0409/movie-recommender-system

## Overview

This is a Streamlit movie-discovery app backed by a FastAPI service. A user browses a category feed or searches for a title, opens its details, and explores TF-IDF and genre recommendations. The backend combines precomputed local recommendation data with live TMDB metadata. The README documents the notebook-to-artifacts training path and additional API capabilities; unsampled implementation details are represented only where that documentation supports them.

Main entry points: [`main.py`](https://github.com/aayush-0409/movie-recommender-system/blob/main/main.py) (Recommendation bundle), [`app.py`](https://github.com/aayush-0409/movie-recommender-system/blob/main/app.py) (Streamlit UI), [`Movie_Recommender_System.ipynb`](https://github.com/aayush-0409/movie-recommender-system/blob/main/Movie_Recommender_System.ipynb) (Model preparation), [`df.pkl`](https://github.com/aayush-0409/movie-recommender-system/blob/main/df.pkl) (Prepared model data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Movie interface"]
  node_streamlit["Streamlit UI<br/>[app.py]"]
end

subgraph group_api["API workflows"]
  node_home["Home feed<br/>[main.py]"]
  node_search["Keyword search<br/>[main.py]"]
  node_details["Movie details<br/>[main.py]"]
  node_bundle["Recommendation bundle<br/>[main.py]"]
  node_genre["Genre recommendations<br/>[main.py]"]
end

subgraph group_recommend["Recommendation data"]
  node_tfidf["TF-IDF ranking<br/>[main.py]"]
  node_model_data[("Prepared model data<br/>[df.pkl]")]
  node_title_index[("Title index<br/>[indices.pkl]")]
  node_vectorizer[("Fitted vectorizer<br/>[tfidf.pkl]")]
  node_vectors[("TF-IDF matrix<br/>[tfidf_matrix.pkl]")]
  node_training["Model preparation"]
end

subgraph group_external["External movie data"]
  node_tmdb{{"TMDB API"}}
end

node_user(("Movie browser"))

node_user -->|"browses"| node_streamlit
node_streamlit -->|"requests feed"| node_home
node_streamlit -->|"requests matches"| node_search
node_streamlit -->|"requests details"| node_details
node_streamlit -->|"requests recommendations"| node_bundle
node_home -->|"fetches feed"| node_tmdb
node_search -->|"searches titles"| node_tmdb
node_details -->|"fetches details"| node_tmdb
node_bundle -->|"finds title"| node_search
node_bundle -->|"fetches details"| node_details
node_bundle -->|"gets similar titles"| node_tfidf
node_bundle -->|"gets genre matches"| node_genre
node_genre -->|"reads genres"| node_details
node_genre -->|"discovers titles"| node_tmdb
node_tfidf -->|"looks up title"| node_title_index
node_tfidf -->|"ranks titles"| node_model_data
node_tfidf -->|"uses model"| node_vectorizer
node_tfidf -->|"computes similarity"| node_vectors
node_bundle -->|"enriches matches"| node_tmdb
node_training -->|"exports metadata"| node_model_data
node_training -->|"exports lookup"| node_title_index
node_training -->|"exports model"| node_vectorizer
node_training -->|"exports matrix"| node_vectors

click node_streamlit "https://github.com/aayush-0409/movie-recommender-system/blob/main/app.py"
click node_home "https://github.com/aayush-0409/movie-recommender-system/blob/main/main.py"
click node_search "https://github.com/aayush-0409/movie-recommender-system/blob/main/main.py"
click node_details "https://github.com/aayush-0409/movie-recommender-system/blob/main/main.py"
click node_bundle "https://github.com/aayush-0409/movie-recommender-system/blob/main/main.py"
click node_genre "https://github.com/aayush-0409/movie-recommender-system/blob/main/main.py"
click node_tfidf "https://github.com/aayush-0409/movie-recommender-system/blob/main/main.py"
click node_model_data "https://github.com/aayush-0409/movie-recommender-system/blob/main/df.pkl"
click node_title_index "https://github.com/aayush-0409/movie-recommender-system/blob/main/indices.pkl"
click node_vectorizer "https://github.com/aayush-0409/movie-recommender-system/blob/main/tfidf.pkl"
click node_vectors "https://github.com/aayush-0409/movie-recommender-system/blob/main/tfidf_matrix.pkl"
click node_training "https://github.com/aayush-0409/movie-recommender-system/blob/main/Movie_Recommender_System.ipynb"

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_streamlit,node_user toneBlue
class node_home,node_search,node_details,node_bundle,node_genre toneAmber
class node_tfidf,node_model_data,node_title_index,node_vectorizer,node_vectors,node_training toneMint
class node_tmdb toneRose
```

## Components

### Movie interface

- [Streamlit UI](https://github.com/aayush-0409/movie-recommender-system/blob/main/app.py): `app.py`

### API workflows

- [Home feed](https://github.com/aayush-0409/movie-recommender-system/blob/main/main.py): `main.py`
- [Keyword search](https://github.com/aayush-0409/movie-recommender-system/blob/main/main.py): `main.py`
- [Movie details](https://github.com/aayush-0409/movie-recommender-system/blob/main/main.py): `main.py`
- [Recommendation bundle](https://github.com/aayush-0409/movie-recommender-system/blob/main/main.py): `main.py`
- [Genre recommendations](https://github.com/aayush-0409/movie-recommender-system/blob/main/main.py): `main.py`

### Recommendation data

- [TF-IDF ranking](https://github.com/aayush-0409/movie-recommender-system/blob/main/main.py): `main.py`
- [Prepared model data](https://github.com/aayush-0409/movie-recommender-system/blob/main/df.pkl): `df.pkl`
- [Title index](https://github.com/aayush-0409/movie-recommender-system/blob/main/indices.pkl): `indices.pkl`
- [Fitted vectorizer](https://github.com/aayush-0409/movie-recommender-system/blob/main/tfidf.pkl): `tfidf.pkl`
- [TF-IDF matrix](https://github.com/aayush-0409/movie-recommender-system/blob/main/tfidf_matrix.pkl): `tfidf_matrix.pkl`
- [Model preparation](https://github.com/aayush-0409/movie-recommender-system/blob/main/Movie_Recommender_System.ipynb): `Movie_Recommender_System.ipynb`

### External movie data

- **TMDB API**

### Other components

- **Movie browser**

## Connections

- Movie browser → Streamlit UI: browses (evidence: `README.md`)
- Streamlit UI → Home feed: requests feed (evidence: `app.py`)
- Streamlit UI → Keyword search: requests matches (evidence: `app.py`)
- Streamlit UI → Movie details: requests details (evidence: `app.py`)
- Streamlit UI → Recommendation bundle: requests recommendations (evidence: `app.py`)
- Home feed → TMDB API: fetches feed (evidence: `main.py`)
- Keyword search → TMDB API: searches titles (evidence: `main.py`)
- Movie details → TMDB API: fetches details (evidence: `main.py`)
- Recommendation bundle → Keyword search: finds title (evidence: `main.py`)
- Recommendation bundle → Movie details: fetches details (evidence: `main.py`)
- Recommendation bundle → TF-IDF ranking: gets similar titles (evidence: `main.py`)
- Recommendation bundle → Genre recommendations: gets genre matches (evidence: `main.py`)
- Genre recommendations → Movie details: reads genres (evidence: `main.py`)
- Genre recommendations → TMDB API: discovers titles (evidence: `README.md`)
- TF-IDF ranking → Title index: looks up title (evidence: `README.md`)
- TF-IDF ranking → Prepared model data: ranks titles (evidence: `README.md`)
- TF-IDF ranking → Fitted vectorizer: uses model (evidence: `README.md`)
- TF-IDF ranking → TF-IDF matrix: computes similarity (evidence: `README.md`)
- Recommendation bundle → TMDB API: enriches matches (evidence: `main.py`)
- Model preparation → Prepared model data: exports metadata (evidence: `README.md`)
- Model preparation → Title index: exports lookup (evidence: `README.md`)
- Model preparation → Fitted vectorizer: exports model (evidence: `README.md`)
- Model preparation → TF-IDF matrix: exports matrix (evidence: `README.md`)
