# yakshini12/ml-recommendation-system architecture

> Architecture diagram of the GitHub repository yakshini12/ml-recommendation-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/yakshini12/ml-recommendation-system
- Repository: https://github.com/yakshini12/ml-recommendation-system

## Overview

This is a Flask movie-recommendation application with title-based content, collaborative, and hybrid lists, plus a genre-based popularity fallback. The visitor submits a title or genre; the app loads a recommender, requests the corresponding lists, and renders them. A separate offline workflow evaluates item recommendations using per-user holdouts. The README documents major model stages not fully visible in the excerpts; the graph uses it for those relationships and omits uncertain implementation details.

Main entry points: [`app.py`](https://github.com/yakshini12/ml-recommendation-system/blob/main/app.py) (Flask route), [`movies.csv`](https://github.com/yakshini12/ml-recommendation-system/blob/main/movies.csv) (Movie catalog), [`evaluate.py`](https://github.com/yakshini12/ml-recommendation-system/blob/main/evaluate.py) (Holdout evaluator), [`model.py`](https://github.com/yakshini12/ml-recommendation-system/blob/main/model.py) (Data loading)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_flask["Flask route<br/>[app.py]"]
  node_page["Recommendation page<br/>[index.html]"]
end

subgraph group_recommend["Recommendation methods"]
  node_content["Content ranking<br/>[model.py]"]
  node_tfidf["Genre TF-IDF<br/>[model.py]"]
  node_collab["Collaborative ranking<br/>[model.py]"]
  node_matrix["Ratings matrix<br/>[model.py]"]
  node_knn["Item KNN<br/>[model.py]"]
  node_titlemap["Neighbor title mapping<br/>[model.py]"]
  node_hybrid["Hybrid ranking<br/>[model.py]"]
  node_cold["Genre popularity fallback<br/>[model.py]"]
end

subgraph group_data["Catalog and ratings"]
  node_loader["Data loading<br/>[model.py]"]
  node_catalog["Movie catalog<br/>[movies.csv]"]
  node_ratings["Demo ratings<br/>[demo_ratings.csv]"]
end

subgraph group_evaluation["Offline evaluation"]
  node_evaluation["Holdout evaluator<br/>[evaluate.py]"]
  node_split["Per-user holdout split<br/>[evaluate.py]"]
  node_metrics["Precision and recall<br/>[evaluate.py]"]
end

node_visitor(("Visitor"))
node_external["External ratings CSV"]

node_visitor -->|"submits request"| node_flask
node_flask -->|"loads recommender"| node_loader
node_loader -->|"loads catalog"| node_catalog
node_loader -->|"loads ratings"| node_ratings
node_flask -->|"requests title list"| node_content
node_flask -->|"requests title list"| node_collab
node_flask -->|"requests title list"| node_hybrid
node_flask -->|"requests genre list"| node_cold
node_content -->|"ranks genre vectors"| node_tfidf
node_catalog -->|"supplies genres"| node_tfidf
node_ratings -->|"forms interactions"| node_matrix
node_matrix -->|"fits neighbors"| node_knn
node_collab -->|"queries neighbors"| node_knn
node_knn -->|"maps neighbor IDs"| node_titlemap
node_catalog -->|"resolves titles"| node_titlemap
node_content -->|"provides scores"| node_hybrid
node_collab -->|"provides scores"| node_hybrid
node_catalog -->|"matches genres"| node_cold
node_ratings -->|"provides interaction counts"| node_cold
node_flask -->|"renders lists"| node_page
node_external -->|"supplies ratings"| node_evaluation
node_catalog -->|"supplies catalog"| node_evaluation
node_evaluation -->|"loads data"| node_loader
node_evaluation -->|"creates holdout"| node_split
node_evaluation -->|"computes metrics"| node_metrics
node_split -->|"provides held-out rows"| node_metrics

click node_flask "https://github.com/yakshini12/ml-recommendation-system/blob/main/app.py"
click node_page "https://github.com/yakshini12/ml-recommendation-system/blob/main/templates/index.html"
click node_loader "https://github.com/yakshini12/ml-recommendation-system/blob/main/model.py"
click node_catalog "https://github.com/yakshini12/ml-recommendation-system/blob/main/movies.csv"
click node_ratings "https://github.com/yakshini12/ml-recommendation-system/blob/main/data/demo_ratings.csv"
click node_content "https://github.com/yakshini12/ml-recommendation-system/blob/main/model.py"
click node_tfidf "https://github.com/yakshini12/ml-recommendation-system/blob/main/model.py"
click node_collab "https://github.com/yakshini12/ml-recommendation-system/blob/main/model.py"
click node_matrix "https://github.com/yakshini12/ml-recommendation-system/blob/main/model.py"
click node_knn "https://github.com/yakshini12/ml-recommendation-system/blob/main/model.py"
click node_titlemap "https://github.com/yakshini12/ml-recommendation-system/blob/main/model.py"
click node_hybrid "https://github.com/yakshini12/ml-recommendation-system/blob/main/model.py"
click node_cold "https://github.com/yakshini12/ml-recommendation-system/blob/main/model.py"
click node_evaluation "https://github.com/yakshini12/ml-recommendation-system/blob/main/evaluate.py"
click node_split "https://github.com/yakshini12/ml-recommendation-system/blob/main/evaluate.py"
click node_metrics "https://github.com/yakshini12/ml-recommendation-system/blob/main/evaluate.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_flask,node_page toneBlue
class node_content,node_tfidf,node_collab,node_matrix,node_knn,node_titlemap,node_hybrid,node_cold toneAmber
class node_loader,node_catalog,node_ratings toneMint
class node_evaluation,node_split,node_metrics toneRose
class node_visitor,node_external toneIndigo
```

## Components

### Web interface

- [Flask route](https://github.com/yakshini12/ml-recommendation-system/blob/main/app.py): `app.py`
- [Recommendation page](https://github.com/yakshini12/ml-recommendation-system/blob/main/templates/index.html): `templates/index.html`

### Recommendation methods

- [Content ranking](https://github.com/yakshini12/ml-recommendation-system/blob/main/model.py): `model.py`
- [Genre TF-IDF](https://github.com/yakshini12/ml-recommendation-system/blob/main/model.py): `model.py`
- [Collaborative ranking](https://github.com/yakshini12/ml-recommendation-system/blob/main/model.py): `model.py`
- [Ratings matrix](https://github.com/yakshini12/ml-recommendation-system/blob/main/model.py): `model.py`
- [Item KNN](https://github.com/yakshini12/ml-recommendation-system/blob/main/model.py): `model.py`
- [Neighbor title mapping](https://github.com/yakshini12/ml-recommendation-system/blob/main/model.py): `model.py`
- [Hybrid ranking](https://github.com/yakshini12/ml-recommendation-system/blob/main/model.py): `model.py`
- [Genre popularity fallback](https://github.com/yakshini12/ml-recommendation-system/blob/main/model.py): `model.py`

### Catalog and ratings

- [Data loading](https://github.com/yakshini12/ml-recommendation-system/blob/main/model.py): `model.py`
- [Movie catalog](https://github.com/yakshini12/ml-recommendation-system/blob/main/movies.csv): `movies.csv`
- [Demo ratings](https://github.com/yakshini12/ml-recommendation-system/blob/main/data/demo_ratings.csv): `data/demo_ratings.csv`

### Offline evaluation

- [Holdout evaluator](https://github.com/yakshini12/ml-recommendation-system/blob/main/evaluate.py): `evaluate.py`
- [Per-user holdout split](https://github.com/yakshini12/ml-recommendation-system/blob/main/evaluate.py): `evaluate.py`
- [Precision and recall](https://github.com/yakshini12/ml-recommendation-system/blob/main/evaluate.py): `evaluate.py`

### Other components

- **Visitor**
- **External ratings CSV**

## Connections

- Visitor → Flask route: submits request (evidence: `README.md`)
- Flask route → Data loading: loads recommender (evidence: `app.py`)
- Data loading → Movie catalog: loads catalog (evidence: `README.md`)
- Data loading → Demo ratings: loads ratings (evidence: `README.md`)
- Flask route → Content ranking: requests title list (evidence: `app.py`)
- Flask route → Collaborative ranking: requests title list (evidence: `app.py`)
- Flask route → Hybrid ranking: requests title list (evidence: `app.py`)
- Flask route → Genre popularity fallback: requests genre list (evidence: `app.py`)
- Content ranking → Genre TF-IDF: ranks genre vectors (evidence: `README.md`)
- Movie catalog → Genre TF-IDF: supplies genres (evidence: `README.md`)
- Demo ratings → Ratings matrix: forms interactions (evidence: `README.md`)
- Ratings matrix → Item KNN: fits neighbors (evidence: `README.md`)
- Collaborative ranking → Item KNN: queries neighbors (evidence: `README.md`)
- Item KNN → Neighbor title mapping: maps neighbor IDs (evidence: `README.md`)
- Movie catalog → Neighbor title mapping: resolves titles (evidence: `README.md`)
- Content ranking → Hybrid ranking: provides scores (evidence: `README.md`)
- Collaborative ranking → Hybrid ranking: provides scores (evidence: `README.md`)
- Movie catalog → Genre popularity fallback: matches genres (evidence: `README.md`)
- Demo ratings → Genre popularity fallback: provides interaction counts (evidence: `README.md`)
- Flask route → Recommendation page: renders lists (evidence: `app.py`)
- External ratings CSV → Holdout evaluator: supplies ratings (evidence: `README.md`)
- Movie catalog → Holdout evaluator: supplies catalog (evidence: `README.md`)
- Holdout evaluator → Data loading: loads data (evidence: `evaluate.py`)
- Holdout evaluator → Per-user holdout split: creates holdout (evidence: `evaluate.py`)
- Holdout evaluator → Precision and recall: computes metrics (evidence: `evaluate.py`)
- Per-user holdout split → Precision and recall: provides held-out rows (evidence: `evaluate.py`)
