# vaibhav3792/movie-recommender-system architecture

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

- Interactive diagram: https://gitdiagram.com/vaibhav3792/movie-recommender-system
- Repository: https://github.com/vaibhav3792/movie-recommender-system

## Overview

1. **Top-level shape**
   - This repo is an **ML recommender system**, not a general web app.
   - It has two main phases:
     - **Offline pipeline**: ingest/clean data, engineer movie features, train recommendation models.
     - **Online inference/UI**: a Streamlit app serves recommendations and explanations.

2. **Data sources and repository-local data**
   - The project is built around **MovieLens 25M** ratings plus **TMDB-style movie metadata**.
   - The only raw mapping file visible in the repo is `data/raw/links.csv`, which is typically used to connect MovieLens movie IDs to TMDB IDs.
   - The cleaned output shown in the tree is `data/processed/movies_clean.csv`, which is the likely canonical input to the recommendation models.

3. **`src/data_pipeline.py` is the preprocessing boundary**
   - This module is the data engineering layer.
   - Its role is to merge/clean the movie metadata, normalize fields like genres/cast/director/overview, and produce the processed dataset used by downstream models.
   - Architecturally, it sits between raw datasets and all model training code.

4. **Content-based recommendation subsystem**
   - `src/content_model.py` implements the movie-content side of the system.
   - From the README, this combines:
     - **TF-IDF** over movie tags/text fields
     - **GloVe word embeddings** for semantic similarity
   - Input is enriched movie metadata; output is a content-similarity score or ranked candidate list based on shared themes, actors, directors, and text semantics.

5. **Collaborative filtering subsystem**
   - `src/collaborative_model.py` handles the rating-based recommender.
   - It uses **matrix factorization / SVD** over the MovieLens ratings matrix to learn latent user/movie preferences.
   - This is the only subsystem that depends on the large user-rating graph rather than movie metadata.

6. **Hybrid fusion layer**
   - `src/hybrid_model.py` is the system’s main recommendation combiner.
   - It blends the content score and collaborative score into a final ranking, matching the README’s described weighted ensemble.
   - This module is the core architectural bridge between “movie similarity” and “taste prediction.”

7. **Explainability layer**
   - `src/explainer.py` adds user-facing rationale to recommendations.
   - It likely derives reasons from metadata overlap such as:
     - similar genres
     - shared cast
     - same director
     - similar themes
   - This is a presentation-facing subsystem, but it depends on the same cleaned metadata used by the content model.

8. **Serving/UI layer**
   - `app.py` is the runtime entrypoint and the app file referenced by the Hugging Face Spaces config.
   - It likely loads the trained artifacts, accepts a movie selection or similar input, calls the hybrid recommender, then renders the ranked results and explanations in the UI.
   - This is the only interactive boundary in the repo.

9. **Model and artifact flow**
   - The README indicates large model files are **not stored in the repo** and are instead loaded from the **Hugging Face Hub** on first run.
   - That means the architecture separates:
     - **source code and lightweight data** in the repo
     - **large trained artifacts** in external model storage
   - This is important for diagramming because inference depends on remote artifact retrieval.

10. **Deployment/runtime**
   - `Dockerfile` and the README metadata show the app is deployed as a **Docker-based Hugging Face Space**.
   - The operational runtime is therefore containerized, with `app.py` as the startup entrypoint.
   - `requirements.txt` defines the Python ML stack needed at runtime: pandas/numpy, scikit-learn/NLTK, Gensim, Surprise, and Streamlit.

11. **Exploratory vs production code**
   - `notebooks/development.ipynb` is clearly exploratory/development-only.
   - The production path is the `src/` modules plus `app.py`; the notebook is not part of the serving architecture.

12. **End-to-end data flow**
   - Raw metadata and ratings → `data_pipeline.py` → cleaned movie dataset/features.
   - Cleaned metadata → `content_model.py` and `explainer.py`.
   - Ratings matrix → `collaborative_model.py`.
   - Both scoring paths → `hybrid_model.py`.
   - Final ranked recommendations + reasons → `app.py` UI.

13. **Key architectural boundary to draw**
   - The most important boundary is between **offline ML preparation/training** and **online recommendation serving**.
   - Another important boundary is between **metadata-based similarity** and **ratings-based latent preference modeling**, with `hybrid_model.py` merging them into a single user-facing result.

Main entry points: [`src/data_pipeline.py`](https://github.com/vaibhav3792/movie-recommender-system/blob/main/src/data_pipeline.py) (Data Pipeline), [`src/__init__.py`](https://github.com/vaibhav3792/movie-recommender-system/blob/main/src/__init__.py) (Src Package), [`app.py`](https://github.com/vaibhav3792/movie-recommender-system/blob/main/app.py) (App), [`src/hybrid_model.py`](https://github.com/vaibhav3792/movie-recommender-system/blob/main/src/hybrid_model.py) (Hybrid Model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_offline["Offline ML"]
  node_pipeline["Data Pipeline<br/>preprocessing<br/>[data_pipeline.py]"]
  node_content["Content Model<br/>metadata recommender<br/>[content_model.py]"]
  node_collab["Collaborative Model<br/>matrix factorization"]
  node_hybrid["Hybrid Model<br/>score fusion<br/>[hybrid_model.py]"]
  node_notebook["Notebook<br/>exploration<br/>[development.ipynb]"]
  node_src_init["Src Package<br/>package init<br/>[__init__.py]"]
end

subgraph group_online["Online Serving"]
  node_app["App<br/>streamlit entrypoint<br/>[app.py]"]
  node_explainer["Explainer<br/>rationale engine<br/>[explainer.py]"]
end

subgraph group_data["Data Assets"]
  node_movies_clean["Cleaned Movies<br/>processed dataset<br/>[movies_clean.csv]"]
  node_links["ID Links<br/>raw mapping<br/>[links.csv]"]
end

subgraph group_external["External Runtime"]
  node_model_hub[("Model Hub<br/>remote artifacts")]
  node_ratings_source[("Ratings Data<br/>movie ratings")]
  node_metadata_source[("Movie Metadata")]
  node_docker["Docker<br/>container runtime"]
  node_requirements["Python Stack<br/>dependencies<br/>[requirements.txt]"]
  node_readme["README<br/>project guide<br/>[README.md]"]
end

node_links -->|"ID mapping"| node_pipeline
node_metadata_source -->|"enrich"| node_pipeline
node_pipeline -->|"writes"| node_movies_clean
node_movies_clean -->|"features"| node_content
node_movies_clean -->|"evidence"| node_explainer
node_ratings_source -->|"train"| node_collab
node_content -->|"content score"| node_hybrid
node_collab -->|"collab score"| node_hybrid
node_hybrid -->|"ranked recs"| node_app
node_explainer -->|"reasons"| node_app
node_model_hub -->|"load artifacts"| node_app
node_requirements -->|"deps"| node_app
node_docker -->|"start"| node_app
node_readme -.->|"describes"| node_pipeline
node_readme -.->|"describes"| node_hybrid
node_readme -.->|"describes"| node_app
node_notebook -.->|"prototypes"| node_pipeline
node_notebook -.->|"prototypes"| node_content
node_notebook -.->|"prototypes"| node_collab
node_src_init -.->|"package"| node_pipeline
node_src_init -.->|"package"| node_content
node_src_init -.->|"package"| node_collab
node_src_init -.->|"package"| node_hybrid
node_src_init -.->|"package"| node_explainer

click node_app "https://github.com/vaibhav3792/movie-recommender-system/blob/main/app.py"
click node_pipeline "https://github.com/vaibhav3792/movie-recommender-system/blob/main/src/data_pipeline.py"
click node_content "https://github.com/vaibhav3792/movie-recommender-system/blob/main/src/content_model.py"
click node_collab "https://github.com/vaibhav3792/movie-recommender-system/blob/main/src/collaborative_model.py"
click node_hybrid "https://github.com/vaibhav3792/movie-recommender-system/blob/main/src/hybrid_model.py"
click node_explainer "https://github.com/vaibhav3792/movie-recommender-system/blob/main/src/explainer.py"
click node_movies_clean "https://github.com/vaibhav3792/movie-recommender-system/blob/main/data/processed/movies_clean.csv"
click node_links "https://github.com/vaibhav3792/movie-recommender-system/blob/main/data/raw/links.csv"
click node_docker "https://github.com/vaibhav3792/movie-recommender-system/tree/main/Dockerfile"
click node_requirements "https://github.com/vaibhav3792/movie-recommender-system/blob/main/requirements.txt"
click node_notebook "https://github.com/vaibhav3792/movie-recommender-system/blob/main/notebooks/development.ipynb"
click node_src_init "https://github.com/vaibhav3792/movie-recommender-system/blob/main/src/__init__.py"
click node_readme "https://github.com/vaibhav3792/movie-recommender-system/blob/main/README.md"

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_pipeline,node_content,node_collab,node_hybrid,node_notebook,node_src_init toneBlue
class node_app,node_explainer toneAmber
class node_movies_clean,node_links toneMint
class node_model_hub,node_ratings_source,node_metadata_source,node_docker,node_requirements,node_readme toneRose
```

## Components

### Offline ML

Data preparation and model-building components.

- [Data Pipeline](https://github.com/vaibhav3792/movie-recommender-system/blob/main/src/data_pipeline.py): preprocessing · Cleans and enriches movie metadata into the processed dataset used downstream. · `src/data_pipeline.py`
- [Content Model](https://github.com/vaibhav3792/movie-recommender-system/blob/main/src/content_model.py): metadata recommender · Computes movie similarity from text and metadata signals such as tags, genres, cast, and embeddings. · `src/content_model.py`
- [Collaborative Model](https://github.com/vaibhav3792/movie-recommender-system/blob/main/src/collaborative_model.py): matrix factorization · Learns latent preferences from the user-item ratings matrix using collaborative filtering / SVD. · `src/collaborative_model.py`
- [Hybrid Model](https://github.com/vaibhav3792/movie-recommender-system/blob/main/src/hybrid_model.py): score fusion · Combines content-based and collaborative scores into the final recommendation ranking. · `src/hybrid_model.py`
- [Notebook](https://github.com/vaibhav3792/movie-recommender-system/blob/main/notebooks/development.ipynb): exploration · Development-only exploratory notebook, outside the production serving path. · `notebooks/development.ipynb`
- [Src Package](https://github.com/vaibhav3792/movie-recommender-system/blob/main/src/__init__.py): package init · Package marker for the model and pipeline modules. · `src/__init__.py`

### Online Serving

Runtime inference and user-facing recommendation delivery.

- [App](https://github.com/vaibhav3792/movie-recommender-system/blob/main/app.py): streamlit entrypoint · Interactive UI that loads models, accepts movie input, and renders recommendations with explanations. · `app.py`
- [Explainer](https://github.com/vaibhav3792/movie-recommender-system/blob/main/src/explainer.py): rationale engine · Generates human-readable reasons for recommendations from shared metadata and semantic overlap. · `src/explainer.py`

### Data Assets

Raw and processed repository-local datasets.

- [Cleaned Movies](https://github.com/vaibhav3792/movie-recommender-system/blob/main/data/processed/movies_clean.csv): processed dataset · Canonical cleaned movie metadata consumed by the recommendation models. · `data/processed/movies_clean.csv`
- [ID Links](https://github.com/vaibhav3792/movie-recommender-system/blob/main/data/raw/links.csv): raw mapping · Maps MovieLens movie identifiers to TMDB-style identifiers used in metadata joins. · `data/raw/links.csv`

### External Runtime

Container and remote artifact dependencies.

- **Model Hub**: remote artifacts · External source for large trained artifacts loaded on first run rather than stored in the repo.
- **Ratings Data**: movie ratings · Large MovieLens ratings corpus that drives collaborative filtering.
- **Movie Metadata**: movie metadata · TMDB-style movie metadata source used to enrich and clean movie features.
- [Docker](https://github.com/vaibhav3792/movie-recommender-system/tree/main/Dockerfile): container runtime · Containerized deployment environment for the Streamlit application. · `Dockerfile`
- [Python Stack](https://github.com/vaibhav3792/movie-recommender-system/blob/main/requirements.txt): dependencies · Runtime ML and UI dependency set used by the app and models. · `requirements.txt`
- [README](https://github.com/vaibhav3792/movie-recommender-system/blob/main/README.md): project guide · Repository overview and setup instructions describing the pipeline and deployment flow. · `README.md`

## Connections

- ID Links → Data Pipeline: ID mapping · Raw movie ID links support metadata joins during preprocessing.
- Movie Metadata → Data Pipeline: enrich · External movie metadata is cleaned and normalized into the processed dataset.
- Data Pipeline → Cleaned Movies: writes · Preprocessing produces the canonical cleaned movie table.
- Cleaned Movies → Content Model: features · Cleaned metadata feeds text and metadata-based similarity modeling.
- Cleaned Movies → Explainer: evidence · Clean metadata provides the fields used to explain recommendations.
- Ratings Data → Collaborative Model: train · Ratings data is used to fit collaborative filtering factors.
- Content Model → Hybrid Model: content score · Content-based ranking contributes one side of the ensemble.
- Collaborative Model → Hybrid Model: collab score · Latent preference scores contribute the other side of the ensemble.
- Hybrid Model → App: ranked recs · The fused recommender returns the final ranked list to the UI.
- Explainer → App: reasons · Explanations are rendered alongside recommendations.
- Model Hub → App: load artifacts · The runtime fetches large trained artifacts externally on first use.
- Python Stack → App: deps · Python dependencies support the serving runtime and model libraries.
- Docker → App: start · Container startup launches the Streamlit application entrypoint.
- README → Data Pipeline: describes · Project documentation outlines the offline data preparation flow.
- README → Hybrid Model: describes · Documentation explains the hybrid ensemble architecture.
- README → App: describes · Documentation covers the deployed app and usage path.
- Notebook → Data Pipeline: prototypes · Exploratory analysis informs preprocessing and modeling decisions.
- Notebook → Content Model: prototypes · Notebook experimentation supports the content recommender design.
- Notebook → Collaborative Model: prototypes · Notebook experimentation supports collaborative filtering development.
- Src Package → Data Pipeline: package · Marks the source directory as a Python package for the model modules.
- Src Package → Content Model: package · Marks the source directory as a Python package for the model modules.
- Src Package → Collaborative Model: package · Marks the source directory as a Python package for the model modules.
- Src Package → Hybrid Model: package · Marks the source directory as a Python package for the model modules.
- Src Package → Explainer: package · Marks the source directory as a Python package for the model modules.