# chhssmch/movie-recsys architecture

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

- Interactive diagram: https://gitdiagram.com/chhssmch/movie-recsys
- Repository: https://github.com/chhssmch/movie-recsys

## Overview

This is an educational MovieLens recommendation system. Its main workflow loads and prepares ratings and movie metadata, builds four recommendation approaches, evaluates their ranked results, and saves metrics. The graph also includes the standalone popularity/genre and similar-item capabilities. The README describes production concerns and monitoring as coursework, not implemented runtime services, so those are not shown as system components.

Main entry points: [`src/data_loader.py`](https://github.com/chhssmch/movie-recsys/blob/master/src/data_loader.py) (Data loading and splitting), [`src/evaluate.py`](https://github.com/chhssmch/movie-recsys/blob/master/src/evaluate.py) (Model evaluation), [`scripts/run_all.py`](https://github.com/chhssmch/movie-recsys/blob/master/scripts/run_all.py) (Pipeline runner), [`src/popularity.py`](https://github.com/chhssmch/movie-recsys/blob/master/src/popularity.py) (Popularity and genre ranking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_raw["MovieLens raw data"]
  node_loader["Data loading and splitting<br/>[data_loader.py]"]
  node_processed["Processed datasets"]
end

subgraph group_models["Recommendation models"]
  node_popularity["Popularity and genre ranking<br/>[popularity.py]"]
  node_content["Content-based recommendations<br/>[content_based.py]"]
  node_itemcf["Item-based CF<br/>[item_based_cf.py]"]
  node_usercf["User-based CF<br/>[user_based_cf.py]"]
end

subgraph group_evaluation["Evaluation and results"]
  node_evaluator["Model evaluation<br/>[evaluate.py]"]
  node_metrics["Evaluation metrics<br/>[metrics.csv]"]
end

subgraph group_entry["Workflow entry"]
  node_runner["Pipeline runner<br/>[run_all.py]"]
end

node_user(("Analyst"))

node_user -->|"starts pipeline"| node_runner
node_runner -->|"loads and splits"| node_loader
node_loader -->|"reads"| node_raw
node_runner -->|"saves processed data"| node_loader
node_loader -->|"writes"| node_processed
node_runner -->|"evaluates models"| node_evaluator
node_evaluator -->|"loads and splits"| node_loader
node_evaluator -->|"builds baseline"| node_popularity
node_evaluator -->|"builds recommender"| node_content
node_evaluator -->|"builds recommender"| node_itemcf
node_evaluator -->|"builds recommender"| node_usercf
node_content -->|"loads movie metadata"| node_loader
node_itemcf -->|"loads ratings and movies"| node_loader
node_usercf -->|"loads ratings and movies"| node_loader
node_popularity -->|"loads ratings and movies"| node_loader
node_runner -->|"writes results"| node_metrics

click node_runner "https://github.com/chhssmch/movie-recsys/blob/master/scripts/run_all.py"
click node_raw "https://github.com/chhssmch/movie-recsys/tree/master/data/raw"
click node_loader "https://github.com/chhssmch/movie-recsys/blob/master/src/data_loader.py"
click node_processed "https://github.com/chhssmch/movie-recsys/tree/master/data/processed"
click node_popularity "https://github.com/chhssmch/movie-recsys/blob/master/src/popularity.py"
click node_content "https://github.com/chhssmch/movie-recsys/blob/master/src/content_based.py"
click node_itemcf "https://github.com/chhssmch/movie-recsys/blob/master/src/item_based_cf.py"
click node_usercf "https://github.com/chhssmch/movie-recsys/blob/master/src/user_based_cf.py"
click node_evaluator "https://github.com/chhssmch/movie-recsys/blob/master/src/evaluate.py"
click node_metrics "https://github.com/chhssmch/movie-recsys/blob/master/reports/metrics.csv"

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_raw,node_loader,node_processed toneBlue
class node_popularity,node_content,node_itemcf,node_usercf toneAmber
class node_evaluator,node_metrics toneMint
class node_runner toneRose
class node_user toneIndigo
```

## Components

### Data preparation

- [MovieLens raw data](https://github.com/chhssmch/movie-recsys/tree/master/data/raw): `data/raw`
- [Data loading and splitting](https://github.com/chhssmch/movie-recsys/blob/master/src/data_loader.py): `src/data_loader.py`
- [Processed datasets](https://github.com/chhssmch/movie-recsys/tree/master/data/processed): `data/processed`

### Recommendation models

- [Popularity and genre ranking](https://github.com/chhssmch/movie-recsys/blob/master/src/popularity.py): `src/popularity.py`
- [Content-based recommendations](https://github.com/chhssmch/movie-recsys/blob/master/src/content_based.py): `src/content_based.py`
- [Item-based CF](https://github.com/chhssmch/movie-recsys/blob/master/src/item_based_cf.py): `src/item_based_cf.py`
- [User-based CF](https://github.com/chhssmch/movie-recsys/blob/master/src/user_based_cf.py): `src/user_based_cf.py`

### Evaluation and results

- [Model evaluation](https://github.com/chhssmch/movie-recsys/blob/master/src/evaluate.py): `src/evaluate.py`
- [Evaluation metrics](https://github.com/chhssmch/movie-recsys/blob/master/reports/metrics.csv): `reports/metrics.csv`

### Workflow entry

- [Pipeline runner](https://github.com/chhssmch/movie-recsys/blob/master/scripts/run_all.py): `scripts/run_all.py`

### Other components

- **Analyst**

## Connections

- Analyst → Pipeline runner: starts pipeline (evidence: `README.md`)
- Pipeline runner → Data loading and splitting: loads and splits (evidence: `scripts/run_all.py`)
- Data loading and splitting → MovieLens raw data: reads (evidence: `src/data_loader.py`)
- Pipeline runner → Data loading and splitting: saves processed data (evidence: `scripts/run_all.py`)
- Data loading and splitting → Processed datasets: writes (evidence: `src/data_loader.py`)
- Pipeline runner → Model evaluation: evaluates models (evidence: `scripts/run_all.py`)
- Model evaluation → Data loading and splitting: loads and splits (evidence: `src/evaluate.py`)
- Model evaluation → Popularity and genre ranking: builds baseline (evidence: `README.md`)
- Model evaluation → Content-based recommendations: builds recommender (evidence: `src/evaluate.py`)
- Model evaluation → Item-based CF: builds recommender (evidence: `src/evaluate.py`)
- Model evaluation → User-based CF: builds recommender (evidence: `src/evaluate.py`)
- Content-based recommendations → Data loading and splitting: loads movie metadata (evidence: `src/content_based.py`)
- Item-based CF → Data loading and splitting: loads ratings and movies (evidence: `src/item_based_cf.py`)
- User-based CF → Data loading and splitting: loads ratings and movies (evidence: `src/user_based_cf.py`)
- Popularity and genre ranking → Data loading and splitting: loads ratings and movies (evidence: `src/popularity.py`)
- Pipeline runner → Evaluation metrics: writes results (evidence: `scripts/run_all.py`)
