# ryanbusby/movierecommender architecture

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

- Interactive diagram: https://gitdiagram.com/ryanbusby/movierecommender
- Repository: https://github.com/ryanbusby/movierecommender

## Overview

This is a Flask movie-recommendation application backed by Spark ALS and MinHashLSH. Users search the movie catalog, submit ratings, and request recommendations; the app finds a similar trained user, gets that user’s ALS recommendations, and renders titles. A separate training path parses ratings, builds sparse user vectors, and fits the models. The tree omits the data and saved model artifacts, so those are shown as external stores. Template and frontend wiring is included where the excerpts show it; other runtime details may be unsampled.

Main entry points: [`app.py`](https://github.com/ryanbusby/movierecommender/blob/main/app.py) (Flask routes), [`src/train.py`](https://github.com/ryanbusby/movierecommender/blob/main/src/train.py) (Model training), [`engine.py`](https://github.com/ryanbusby/movierecommender/blob/main/engine.py) (Recommendation engine), [`movies.py`](https://github.com/ryanbusby/movierecommender/blob/main/movies.py) (Movie lookup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_flask["Flask routes<br/>[app.py]"]
  node_autocomplete["Autocomplete UI<br/>[form.js]"]
  node_browse["Browse page<br/>[index.html]"]
  node_ratings["Rating pages<br/>[movies.html]"]
  node_rate["Rate page<br/>[rate.html]"]
  node_results["Results page<br/>[results.html]"]
end

subgraph group_recommend["Recommendation runtime"]
  node_engine["Recommendation engine<br/>[engine.py]"]
  node_similarity["MinHash matching<br/>[engine.py]"]
  node_als_runtime["ALS recommendations<br/>[engine.py]"]
  node_minhash_model[("Saved MinHash model")]
  node_als_model[("Saved ALS model")]
  node_sparse_store[("User vectors")]
end

subgraph group_training["Model training"]
  node_parser["Ratings parser<br/>[parser.py]"]
  node_trainer["Model training<br/>[train.py]"]
  node_raw_ratings[("Netflix ratings")]
end

subgraph group_catalog["Movie catalog"]
  node_movie_dict["Movie lookup<br/>[movies.py]"]
  node_movie_catalog[("Movie titles")]
end

node_user(("Movie user"))

node_user -->|"uses"| node_flask
node_flask -->|"requests recommendations"| node_engine
node_flask -->|"looks up titles"| node_movie_dict
node_flask -->|"renders"| node_browse
node_flask -->|"renders"| node_ratings
node_flask -->|"renders"| node_rate
node_flask -->|"renders"| node_results
node_autocomplete -->|"fetches suggestions"| node_flask
node_engine -->|"finds neighbor"| node_similarity
node_similarity -->|"queries"| node_minhash_model
node_similarity -->|"compares vectors"| node_sparse_store
node_engine -->|"gets recommendations"| node_als_runtime
node_als_runtime -->|"queries"| node_als_model
node_trainer -->|"parses ratings"| node_parser
node_parser -->|"reads"| node_raw_ratings
node_trainer -->|"fits and saves"| node_als_model
node_trainer -->|"fits and saves"| node_minhash_model
node_trainer -->|"saves vectors"| node_sparse_store
node_flask -->|"loads catalog"| node_movie_dict
node_movie_dict -->|"reads titles"| node_movie_catalog

click node_flask "https://github.com/ryanbusby/movierecommender/blob/main/app.py"
click node_autocomplete "https://github.com/ryanbusby/movierecommender/blob/main/static/js/form.js"
click node_browse "https://github.com/ryanbusby/movierecommender/blob/main/templates/index.html"
click node_ratings "https://github.com/ryanbusby/movierecommender/blob/main/templates/movies.html"
click node_rate "https://github.com/ryanbusby/movierecommender/blob/main/templates/rate.html"
click node_results "https://github.com/ryanbusby/movierecommender/blob/main/templates/results.html"
click node_engine "https://github.com/ryanbusby/movierecommender/blob/main/engine.py"
click node_similarity "https://github.com/ryanbusby/movierecommender/blob/main/engine.py"
click node_als_runtime "https://github.com/ryanbusby/movierecommender/blob/main/engine.py"
click node_parser "https://github.com/ryanbusby/movierecommender/blob/main/src/parser.py"
click node_trainer "https://github.com/ryanbusby/movierecommender/blob/main/src/train.py"
click node_movie_dict "https://github.com/ryanbusby/movierecommender/blob/main/movies.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_autocomplete,node_browse,node_ratings,node_rate,node_results,node_user toneBlue
class node_engine,node_similarity,node_als_runtime,node_minhash_model,node_als_model,node_sparse_store toneAmber
class node_parser,node_trainer,node_raw_ratings toneMint
class node_movie_dict,node_movie_catalog toneRose
```

## Components

### Web application

- [Flask routes](https://github.com/ryanbusby/movierecommender/blob/main/app.py): `app.py`
- [Autocomplete UI](https://github.com/ryanbusby/movierecommender/blob/main/static/js/form.js): `static/js/form.js`
- [Browse page](https://github.com/ryanbusby/movierecommender/blob/main/templates/index.html): `templates/index.html`
- [Rating pages](https://github.com/ryanbusby/movierecommender/blob/main/templates/movies.html): `templates/movies.html`
- [Rate page](https://github.com/ryanbusby/movierecommender/blob/main/templates/rate.html): `templates/rate.html`
- [Results page](https://github.com/ryanbusby/movierecommender/blob/main/templates/results.html): `templates/results.html`

### Recommendation runtime

- [Recommendation engine](https://github.com/ryanbusby/movierecommender/blob/main/engine.py): `engine.py`
- [MinHash matching](https://github.com/ryanbusby/movierecommender/blob/main/engine.py): `engine.py`
- [ALS recommendations](https://github.com/ryanbusby/movierecommender/blob/main/engine.py): `engine.py`
- **Saved MinHash model**
- **Saved ALS model**
- **User vectors**

### Model training

- [Ratings parser](https://github.com/ryanbusby/movierecommender/blob/main/src/parser.py): `src/parser.py`
- [Model training](https://github.com/ryanbusby/movierecommender/blob/main/src/train.py): `src/train.py`
- **Netflix ratings**

### Movie catalog

- [Movie lookup](https://github.com/ryanbusby/movierecommender/blob/main/movies.py): `movies.py`
- **Movie titles**

### Other components

- **Movie user**

## Connections

- Movie user → Flask routes: uses (evidence: `README.md`)
- Flask routes → Recommendation engine: requests recommendations (evidence: `app.py`)
- Flask routes → Movie lookup: looks up titles (evidence: `app.py`)
- Flask routes → Browse page: renders (evidence: `app.py`)
- Flask routes → Rating pages: renders (evidence: `app.py`)
- Flask routes → Rate page: renders (evidence: `app.py`)
- Flask routes → Results page: renders (evidence: `app.py`)
- Autocomplete UI → Flask routes: fetches suggestions (evidence: `static/js/form.js`)
- Recommendation engine → MinHash matching: finds neighbor (evidence: `engine.py`)
- MinHash matching → Saved MinHash model: queries (evidence: `engine.py`)
- MinHash matching → User vectors: compares vectors (evidence: `engine.py`)
- Recommendation engine → ALS recommendations: gets recommendations (evidence: `engine.py`)
- ALS recommendations → Saved ALS model: queries (evidence: `engine.py`)
- Model training → Ratings parser: parses ratings (evidence: `src/train.py`)
- Ratings parser → Netflix ratings: reads (evidence: `src/parser.py`)
- Model training → Saved ALS model: fits and saves (evidence: `src/train.py`)
- Model training → Saved MinHash model: fits and saves (evidence: `src/train.py`)
- Model training → User vectors: saves vectors (evidence: `src/train.py`)
- Flask routes → Movie lookup: loads catalog (evidence: `app.py`)
- Movie lookup → Movie titles: reads titles (evidence: `movies.py`)
