# kunalgehlot73/hybrid-movie-recommendation-system architecture

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

- Interactive diagram: https://gitdiagram.com/kunalgehlot73/hybrid-movie-recommendation-system
- Repository: https://github.com/kunalgehlot73/hybrid-movie-recommendation-system

## Overview

This repository is a MovieLens implicit-feedback recommender: ratings are prepared into user–movie interactions, a VAE learns collaborative relevance, and genre similarity plus popularity rerank candidates into Top-10 results. The web API also supports selecting five catalog movies for recommendations and enriches movie presentation through TMDB. Evaluation, ItemKNN/BPR-MF baselines, and recommendation analysis are separate product capabilities. Source excerpts support the main recommender and web links; some offline workflow links are documented by the README rather than sampled source.

Main entry points: [`utils/recommender.py`](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/utils/recommender.py) (Hybrid recommender), [`preprocess.py`](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/preprocess.py) (Prepare interactions), [`models/vae.py`](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/models/vae.py) (Variational autoencoder), [`utils/training_utils.py`](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/utils/training_utils.py) (Training utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_prep["Prepare interactions<br/>[preprocess.py]"]
  node_loader["MovieLens loading<br/>[data_loader.py]"]
  node_encoding["ID encoding<br/>[encoder.py]"]
  node_interaction["Interaction matrix<br/>[interaction.py]"]
  node_splitter["Per-user split<br/>[splitter.py]"]
  node_matrix[("Train/test matrices")]
end

subgraph group_model["VAE modeling"]
  node_train["Train VAE<br/>[train.py]"]
  node_training["Training utilities<br/>[training_utils.py]"]
  node_annealing["KL annealing<br/>[kl_annealing.py]"]
  node_vae["Variational autoencoder<br/>[vae.py]"]
  node_encoder["VAE encoder<br/>[encoder.py]"]
  node_decoder["VAE decoder<br/>[decoder.py]"]
  node_sampling["Latent sampling<br/>[sampling.py]"]
end

subgraph group_recommend["Recommendation"]
  node_recommender["Hybrid recommender<br/>[recommender.py]"]
  node_genre["Genre profiling<br/>[genre_utils.py]"]
  node_recommend_cli["Recommendation workflow<br/>[recommend.py]"]
end

subgraph group_web["Web experience"]
  node_api["Recommendation API<br/>[main.py]"]
  node_service["Recommendation service"]
  node_tmdb["Movie enrichment<br/>[tmdb_service.py]"]
end

subgraph group_evaluation["Evaluation and analysis"]
  node_metrics["Ranking metrics"]
  node_evaluate["Evaluate recommendations<br/>[evaluate.py]"]
  node_itemknn["ItemKNN baseline<br/>[item_knn.py]"]
  node_bpr["BPR-MF baseline<br/>[bpr_mf.py]"]
  node_eda["Dataset exploration<br/>[eda.py]"]
  node_eda_plots["EDA plots<br/>[eda_plots.py]"]
  node_analysis["Recommendation analysis"]
end

node_actor(("Recommendation user"))
node_tmdb_service(("TMDB"))

node_prep -->|"loads dataset"| node_loader
node_prep -->|"encodes IDs"| node_encoding
node_prep -->|"builds interactions"| node_interaction
node_prep -->|"splits interactions"| node_splitter
node_prep -->|"writes matrices"| node_matrix
node_train -->|"reads training data"| node_matrix
node_train -->|"uses training helpers"| node_training
node_training -->|"registers callback"| node_annealing
node_training -.->|"trains model"| node_vae
node_vae -->|"builds encoder"| node_encoder
node_vae -->|"builds decoder"| node_decoder
node_encoder -->|"samples latent"| node_sampling
node_actor -.->|"requests recommendations"| node_api
node_api -->|"routes requests"| node_service
node_service -->|"generates scores"| node_recommender
node_recommender -->|"predicts relevance"| node_vae
node_recommender -->|"uses genre features"| node_genre
node_service -->|"requests enrichment"| node_tmdb
node_tmdb -->|"fetches movie data"| node_tmdb_service
node_recommend_cli -->|"uses recommender"| node_recommender
node_evaluate -->|"evaluates rankings"| node_recommender
node_evaluate -->|"computes metrics"| node_metrics
node_itemknn -->|"uses shared data"| node_matrix
node_bpr -->|"uses shared data"| node_matrix
node_eda -->|"loads dataset"| node_loader
node_eda -->|"creates plots"| node_eda_plots
node_analysis -->|"analyzes output"| node_recommender

click node_prep "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/preprocess.py"
click node_loader "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/utils/data_loader.py"
click node_encoding "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/utils/encoder.py"
click node_interaction "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/utils/interaction.py"
click node_splitter "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/utils/splitter.py"
click node_train "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/train.py"
click node_training "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/utils/training_utils.py"
click node_annealing "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/callbacks/kl_annealing.py"
click node_vae "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/models/vae.py"
click node_encoder "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/models/encoder.py"
click node_decoder "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/models/decoder.py"
click node_sampling "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/models/sampling.py"
click node_recommender "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/utils/recommender.py"
click node_genre "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/utils/genre_utils.py"
click node_recommend_cli "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/recommend.py"
click node_api "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/web/backend/main.py"
click node_service "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/web/backend/recommender_service.py"
click node_tmdb "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/web/backend/tmdb_service.py"
click node_metrics "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/utils/evaluation_metrics.py"
click node_evaluate "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/evaluate.py"
click node_itemknn "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/baselines/item_knn.py"
click node_bpr "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/baselines/bpr_mf.py"
click node_eda "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/eda.py"
click node_eda_plots "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/utils/eda_plots.py"
click node_analysis "https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/analyze_recommendations.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_prep,node_loader,node_encoding,node_interaction,node_splitter,node_matrix,node_actor toneBlue
class node_train,node_training,node_annealing,node_vae,node_encoder,node_decoder,node_sampling toneAmber
class node_recommender,node_genre,node_recommend_cli toneMint
class node_api,node_service,node_tmdb toneRose
class node_metrics,node_evaluate,node_itemknn,node_bpr,node_eda,node_eda_plots,node_analysis,node_tmdb_service toneIndigo
```

## Components

### Data preparation

- [Prepare interactions](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/preprocess.py): `preprocess.py`
- [MovieLens loading](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/utils/data_loader.py): `utils/data_loader.py`
- [ID encoding](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/utils/encoder.py): `utils/encoder.py`
- [Interaction matrix](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/utils/interaction.py): `utils/interaction.py`
- [Per-user split](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/utils/splitter.py): `utils/splitter.py`
- **Train/test matrices**

### VAE modeling

- [Train VAE](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/train.py): `train.py`
- [Training utilities](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/utils/training_utils.py): `utils/training_utils.py`
- [KL annealing](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/callbacks/kl_annealing.py): `callbacks/kl_annealing.py`
- [Variational autoencoder](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/models/vae.py): `models/vae.py`
- [VAE encoder](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/models/encoder.py): `models/encoder.py`
- [VAE decoder](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/models/decoder.py): `models/decoder.py`
- [Latent sampling](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/models/sampling.py): `models/sampling.py`

### Recommendation

- [Hybrid recommender](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/utils/recommender.py): `utils/recommender.py`
- [Genre profiling](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/utils/genre_utils.py): `utils/genre_utils.py`
- [Recommendation workflow](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/recommend.py): `recommend.py`

### Web experience

- [Recommendation API](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/web/backend/main.py): `web/backend/main.py`
- [Recommendation service](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/web/backend/recommender_service.py): `web/backend/recommender_service.py`
- [Movie enrichment](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/web/backend/tmdb_service.py): `web/backend/tmdb_service.py`

### Evaluation and analysis

- [Ranking metrics](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/utils/evaluation_metrics.py): `utils/evaluation_metrics.py`
- [Evaluate recommendations](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/evaluate.py): `evaluate.py`
- [ItemKNN baseline](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/baselines/item_knn.py): `baselines/item_knn.py`
- [BPR-MF baseline](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/baselines/bpr_mf.py): `baselines/bpr_mf.py`
- [Dataset exploration](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/eda.py): `eda.py`
- [EDA plots](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/utils/eda_plots.py): `utils/eda_plots.py`
- [Recommendation analysis](https://github.com/kunalgehlot73/hybrid-movie-recommendation-system/blob/master/analyze_recommendations.py): `analyze_recommendations.py`

### Other components

- **Recommendation user**
- **TMDB**

## Connections

- Prepare interactions → MovieLens loading: loads dataset (evidence: `preprocess.py`)
- Prepare interactions → ID encoding: encodes IDs (evidence: `preprocess.py`)
- Prepare interactions → Interaction matrix: builds interactions (evidence: `preprocess.py`)
- Prepare interactions → Per-user split: splits interactions (evidence: `preprocess.py`)
- Prepare interactions → Train/test matrices: writes matrices (evidence: `README.md`)
- Train VAE → Train/test matrices: reads training data (evidence: `README.md`)
- Train VAE → Training utilities: uses training helpers (evidence: `train.py`)
- Training utilities → KL annealing: registers callback (evidence: `utils/training_utils.py`)
- Training utilities → Variational autoencoder: trains model
- Variational autoencoder → VAE encoder: builds encoder (evidence: `models/vae.py`)
- Variational autoencoder → VAE decoder: builds decoder (evidence: `models/vae.py`)
- VAE encoder → Latent sampling: samples latent (evidence: `models/encoder.py`)
- Recommendation user → Recommendation API: requests recommendations
- Recommendation API → Recommendation service: routes requests (evidence: `web/backend/main.py`)
- Recommendation service → Hybrid recommender: generates scores (evidence: `web/backend/recommender_service.py`)
- Hybrid recommender → Variational autoencoder: predicts relevance (evidence: `utils/recommender.py`)
- Hybrid recommender → Genre profiling: uses genre features (evidence: `utils/recommender.py`)
- Recommendation service → Movie enrichment: requests enrichment (evidence: `web/backend/recommender_service.py`)
- Movie enrichment → TMDB: fetches movie data (evidence: `web/backend/tmdb_service.py`)
- Recommendation workflow → Hybrid recommender: uses recommender (evidence: `recommend.py`)
- Evaluate recommendations → Hybrid recommender: evaluates rankings (evidence: `evaluate.py`)
- Evaluate recommendations → Ranking metrics: computes metrics (evidence: `evaluate.py`)
- ItemKNN baseline → Train/test matrices: uses shared data (evidence: `README.md`)
- BPR-MF baseline → Train/test matrices: uses shared data (evidence: `baselines/bpr_mf.py`)
- Dataset exploration → MovieLens loading: loads dataset (evidence: `eda.py`)
- Dataset exploration → EDA plots: creates plots (evidence: `eda.py`)
- Recommendation analysis → Hybrid recommender: analyzes output (evidence: `analyze_recommendations.py`)
