# anas-s-muhammed/movie-recommender architecture

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

- Interactive diagram: https://gitdiagram.com/anas-s-muhammed/movie-recommender
- Repository: https://github.com/anas-s-muhammed/movie-recommender

## Overview

ReelMatch is a local Streamlit movie-recommendation app backed by MovieLens 100K. The main path loads and validates ratings and metadata, fits collaborative and genre similarity, ranks candidates from selected seed movies, and displays explainable results. The graph also preserves the separately documented offline evaluation workflow. Source excerpts show the app and evaluation script invoking the engine; the dataset files are represented as inputs. No database or external runtime service is shown.

Main entry points: [`src/movie_recommender/engine.py`](https://github.com/anas-s-muhammed/movie-recommender/blob/main/src/movie_recommender/engine.py) (Load and validate), [`scripts/evaluate.py`](https://github.com/anas-s-muhammed/movie-recommender/blob/main/scripts/evaluate.py) (Leave-one-out evaluation), [`app.py`](https://github.com/anas-s-muhammed/movie-recommender/blob/main/app.py) (Cached model setup), [`data/u.data`](https://github.com/anas-s-muhammed/movie-recommender/blob/main/data/u.data) (Ratings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["MovieLens data"]
  node_ratings["Ratings<br/>[u.data]"]
  node_metadata["Movie metadata<br/>[u.item]"]
end

subgraph group_engine["Recommendation engine"]
  node_loader["Load and validate<br/>[engine.py]"]
  node_centering["User-mean centering<br/>[engine.py]"]
  node_collaborative["Collaborative similarity<br/>[engine.py]"]
  node_genre["Genre similarity<br/>[engine.py]"]
  node_hybrid["Hybrid ranking<br/>[engine.py]"]
  node_catalog["Catalog statistics<br/>[engine.py]"]
end

subgraph group_app["Streamlit application"]
  node_selection["Movie selection<br/>[app.py]"]
  node_settings["Recommendation settings<br/>[app.py]"]
  node_model_setup["Cached model setup<br/>[app.py]"]
  node_results["Ranked results<br/>[app.py]"]
end

subgraph group_evaluation["Offline evaluation"]
  node_evaluation["Leave-one-out evaluation<br/>[evaluate.py]"]
  node_metrics["Ranking metrics<br/>[evaluate.py]"]
end

node_user(("Movie seeker"))

node_ratings -->|"ratings input"| node_loader
node_metadata -->|"metadata input"| node_loader
node_loader -->|"centers ratings"| node_centering
node_centering -->|"computes similarity"| node_collaborative
node_loader -->|"provides genres"| node_genre
node_loader -->|"aggregates ratings"| node_catalog
node_collaborative -->|"blends scores"| node_hybrid
node_genre -->|"blends scores"| node_hybrid
node_user -->|"chooses movies"| node_selection
node_user -->|"sets filters"| node_settings
node_model_setup -->|"loads data"| node_loader
node_model_setup -->|"fits model"| node_collaborative
node_model_setup -->|"fits model"| node_genre
node_selection -->|"requests recommendations"| node_hybrid
node_settings -->|"sets ranking options"| node_hybrid
node_hybrid -->|"returns ranked movies"| node_results
node_catalog -->|"supplies titles"| node_selection
node_ratings -->|"evaluation input"| node_evaluation
node_metadata -->|"evaluation input"| node_evaluation
node_evaluation -->|"fits and ranks"| node_hybrid
node_evaluation -->|"computes hit rate and MRR"| node_metrics

click node_ratings "https://github.com/anas-s-muhammed/movie-recommender/blob/main/data/u.data"
click node_metadata "https://github.com/anas-s-muhammed/movie-recommender/blob/main/data/u.item"
click node_loader "https://github.com/anas-s-muhammed/movie-recommender/blob/main/src/movie_recommender/engine.py"
click node_centering "https://github.com/anas-s-muhammed/movie-recommender/blob/main/src/movie_recommender/engine.py"
click node_collaborative "https://github.com/anas-s-muhammed/movie-recommender/blob/main/src/movie_recommender/engine.py"
click node_genre "https://github.com/anas-s-muhammed/movie-recommender/blob/main/src/movie_recommender/engine.py"
click node_hybrid "https://github.com/anas-s-muhammed/movie-recommender/blob/main/src/movie_recommender/engine.py"
click node_catalog "https://github.com/anas-s-muhammed/movie-recommender/blob/main/src/movie_recommender/engine.py"
click node_selection "https://github.com/anas-s-muhammed/movie-recommender/blob/main/app.py"
click node_settings "https://github.com/anas-s-muhammed/movie-recommender/blob/main/app.py"
click node_model_setup "https://github.com/anas-s-muhammed/movie-recommender/blob/main/app.py"
click node_results "https://github.com/anas-s-muhammed/movie-recommender/blob/main/app.py"
click node_evaluation "https://github.com/anas-s-muhammed/movie-recommender/blob/main/scripts/evaluate.py"
click node_metrics "https://github.com/anas-s-muhammed/movie-recommender/blob/main/scripts/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_ratings,node_metadata toneBlue
class node_loader,node_centering,node_collaborative,node_genre,node_hybrid,node_catalog toneAmber
class node_selection,node_settings,node_model_setup,node_results toneMint
class node_evaluation,node_metrics toneRose
class node_user toneIndigo
```

## Components

### MovieLens data

- [Ratings](https://github.com/anas-s-muhammed/movie-recommender/blob/main/data/u.data): `data/u.data`
- [Movie metadata](https://github.com/anas-s-muhammed/movie-recommender/blob/main/data/u.item): `data/u.item`

### Recommendation engine

- [Load and validate](https://github.com/anas-s-muhammed/movie-recommender/blob/main/src/movie_recommender/engine.py): `src/movie_recommender/engine.py`
- [User-mean centering](https://github.com/anas-s-muhammed/movie-recommender/blob/main/src/movie_recommender/engine.py): `src/movie_recommender/engine.py`
- [Collaborative similarity](https://github.com/anas-s-muhammed/movie-recommender/blob/main/src/movie_recommender/engine.py): `src/movie_recommender/engine.py`
- [Genre similarity](https://github.com/anas-s-muhammed/movie-recommender/blob/main/src/movie_recommender/engine.py): `src/movie_recommender/engine.py`
- [Hybrid ranking](https://github.com/anas-s-muhammed/movie-recommender/blob/main/src/movie_recommender/engine.py): `src/movie_recommender/engine.py`
- [Catalog statistics](https://github.com/anas-s-muhammed/movie-recommender/blob/main/src/movie_recommender/engine.py): `src/movie_recommender/engine.py`

### Streamlit application

- [Movie selection](https://github.com/anas-s-muhammed/movie-recommender/blob/main/app.py): `app.py`
- [Recommendation settings](https://github.com/anas-s-muhammed/movie-recommender/blob/main/app.py): `app.py`
- [Cached model setup](https://github.com/anas-s-muhammed/movie-recommender/blob/main/app.py): `app.py`
- [Ranked results](https://github.com/anas-s-muhammed/movie-recommender/blob/main/app.py): `app.py`

### Offline evaluation

- [Leave-one-out evaluation](https://github.com/anas-s-muhammed/movie-recommender/blob/main/scripts/evaluate.py): `scripts/evaluate.py`
- [Ranking metrics](https://github.com/anas-s-muhammed/movie-recommender/blob/main/scripts/evaluate.py): `scripts/evaluate.py`

### Other components

- **Movie seeker**

## Connections

- Ratings → Load and validate: ratings input (evidence: `README.md`)
- Movie metadata → Load and validate: metadata input (evidence: `README.md`)
- Load and validate → User-mean centering: centers ratings (evidence: `src/movie_recommender/engine.py`)
- User-mean centering → Collaborative similarity: computes similarity (evidence: `src/movie_recommender/engine.py`)
- Load and validate → Genre similarity: provides genres (evidence: `src/movie_recommender/engine.py`)
- Load and validate → Catalog statistics: aggregates ratings (evidence: `src/movie_recommender/engine.py`)
- Collaborative similarity → Hybrid ranking: blends scores (evidence: `src/movie_recommender/engine.py`)
- Genre similarity → Hybrid ranking: blends scores (evidence: `src/movie_recommender/engine.py`)
- Movie seeker → Movie selection: chooses movies (evidence: `README.md`)
- Movie seeker → Recommendation settings: sets filters (evidence: `app.py`)
- Cached model setup → Load and validate: loads data (evidence: `app.py`)
- Cached model setup → Collaborative similarity: fits model (evidence: `app.py`)
- Cached model setup → Genre similarity: fits model (evidence: `app.py`)
- Movie selection → Hybrid ranking: requests recommendations (evidence: `app.py`)
- Recommendation settings → Hybrid ranking: sets ranking options (evidence: `app.py`)
- Hybrid ranking → Ranked results: returns ranked movies (evidence: `app.py`)
- Catalog statistics → Movie selection: supplies titles (evidence: `app.py`)
- Ratings → Leave-one-out evaluation: evaluation input (evidence: `README.md`)
- Movie metadata → Leave-one-out evaluation: evaluation input (evidence: `README.md`)
- Leave-one-out evaluation → Hybrid ranking: fits and ranks (evidence: `scripts/evaluate.py`)
- Leave-one-out evaluation → Ranking metrics: computes hit rate and MRR (evidence: `scripts/evaluate.py`)