# nexus69420/movie-recommender-streamlit architecture

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

- Interactive diagram: https://gitdiagram.com/nexus69420/movie-recommender-streamlit
- Repository: https://github.com/nexus69420/movie-recommender-streamlit

## Overview

#### Purpose and Runtime

This is a Python/Streamlit hybrid movie recommendation application. It combines TMDB-derived movie metadata with MovieLens user ratings to return five recommendations for a selected movie and user ID. The runnable application entry point is `app.py`; `main.ipynb` is likely the exploratory/training workflow.

#### Application Entry Point

`app.py` hosts the Streamlit web interface and recommendation orchestration. It accepts user-facing inputs—movie selection and user ID—and renders the recommended titles and fetched poster imagery.

Grounding:
- `app.py`
- `README.md`

#### Content-Based Recommendation Stage

The content model derives movie similarity from textual and categorical attributes: overview, genres, cast, keywords, and director. These signals form the movie-content representation used to find movies similar to the input title.

The training/preprocessing implementation is not visible in the supplied tree; `main.ipynb` is the likely location for dataset preparation and model experimentation.

Grounding:
- `main.ipynb`
- `README.md`

#### Collaborative Recommendation Stage

Collaborative filtering uses MovieLens user ratings and an SVD model from the Surprise library. Given a user ID, this component estimates that user’s affinity for candidate movies based on rating patterns shared with similar users.

Grounding:
- `app.py`
- `README.md`

#### Hybrid Ranking Boundary

The core system boundary is the hybrid combiner: content similarity generates relevance from the selected movie, while SVD-derived predictions personalize those candidates for the supplied user. The result is ranked and truncated to five movies before presentation.

Control flow: Streamlit input → content candidate/relevance scoring → collaborative prediction for user/candidates → combined ranking → five recommendations.

Grounding:
- `app.py`
- `README.md`

#### External Data and Services

TMDB supplies movie metadata used by the content-based side of the system. MovieLens supplies user-rating data for collaborative filtering. OMDb is called to retrieve poster images for displayed recommendations; this is an external API boundary and may require network access/API credentials.

Grounding:
- `app.py`
- `README.md`

#### Delivery Surface

The only declared delivery surface is a Streamlit web UI rather than a separate API or service layer. The notebook should be treated as an offline development/training environment, while `app.py` is the interactive inference and display runtime.

Grounding:
- `app.py`
- `main.ipynb`

Main entry points: [`main.ipynb`](https://github.com/nexus69420/movie-recommender-streamlit/blob/main/main.ipynb) (Training workflow), [`app.py`](https://github.com/nexus69420/movie-recommender-streamlit/blob/main/app.py) (Content candidate scoring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_offline["Offline development"]
  node_notebook["Training workflow<br/>Notebook<br/>[main.ipynb]"]
  node_content_model["Content similarity model<br/>Content recommender"]
  node_svd_model["Surprise SVD model<br/>Collaborative recommender"]
end

subgraph group_runtime["Streamlit runtime"]
  node_app["Streamlit application<br/>Application entry point<br/>[app.py]"]
  node_user_input["Movie and user input<br/>UI input<br/>[app.py]"]
  node_candidate_scoring["Content candidate scoring<br/>Recommendation stage<br/>[app.py]"]
  node_personalization["Collaborative prediction<br/>Recommendation stage<br/>[app.py]"]
  node_hybrid_ranking["Hybrid ranking<br/>Ranking boundary<br/>[app.py]"]
  node_recommendations["Recommendation display<br/>UI output<br/>[app.py]"]
end

subgraph group_external["External data &amp; APIs"]
  node_tmdb[("TMDB metadata<br/>Movie metadata source")]
  node_movielens[("MovieLens ratings<br/>Ratings dataset")]
  node_omdb{{"OMDb poster API<br/>External API"}}
end

node_tmdb -->|"metadata"| node_notebook
node_movielens -->|"ratings"| node_notebook
node_notebook -->|"builds"| node_content_model
node_notebook -->|"trains"| node_svd_model
node_app -->|"collects"| node_user_input
node_user_input -->|"selected movie"| node_candidate_scoring
node_content_model -->|"similarity"| node_candidate_scoring
node_candidate_scoring -->|"candidates"| node_personalization
node_svd_model -->|"predictions"| node_personalization
node_personalization -->|"user scores"| node_hybrid_ranking
node_candidate_scoring -->|"relevance"| node_hybrid_ranking
node_hybrid_ranking -->|"five movies"| node_recommendations
node_omdb -->|"posters"| node_recommendations

click node_notebook "https://github.com/nexus69420/movie-recommender-streamlit/blob/main/main.ipynb"
click node_app "https://github.com/nexus69420/movie-recommender-streamlit/blob/main/app.py"
click node_user_input "https://github.com/nexus69420/movie-recommender-streamlit/blob/main/app.py"
click node_candidate_scoring "https://github.com/nexus69420/movie-recommender-streamlit/blob/main/app.py"
click node_personalization "https://github.com/nexus69420/movie-recommender-streamlit/blob/main/app.py"
click node_hybrid_ranking "https://github.com/nexus69420/movie-recommender-streamlit/blob/main/app.py"
click node_recommendations "https://github.com/nexus69420/movie-recommender-streamlit/blob/main/app.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_notebook,node_content_model,node_svd_model toneBlue
class node_app,node_user_input,node_candidate_scoring,node_personalization,node_hybrid_ranking,node_recommendations toneAmber
class node_tmdb,node_movielens,node_omdb toneMint
```

## Components

### Offline development

- [Training workflow](https://github.com/nexus69420/movie-recommender-streamlit/blob/main/main.ipynb): Notebook · Prepares data and experiments with recommendation models. · `main.ipynb`
- **Content similarity model**: Content recommender · Represents overview, genres, cast, keywords, and director.
- **Surprise SVD model**: Collaborative recommender · Predicts user affinity from rating patterns.

### Streamlit runtime

- [Streamlit application](https://github.com/nexus69420/movie-recommender-streamlit/blob/main/app.py): Application entry point · Interactive inference and presentation runtime. · `app.py`
- [Movie and user input](https://github.com/nexus69420/movie-recommender-streamlit/blob/main/app.py): UI input · `app.py`
- [Content candidate scoring](https://github.com/nexus69420/movie-recommender-streamlit/blob/main/app.py): Recommendation stage · Finds movies relevant to the selected title. · `app.py`
- [Collaborative prediction](https://github.com/nexus69420/movie-recommender-streamlit/blob/main/app.py): Recommendation stage · Scores candidates for the supplied user ID. · `app.py`
- [Hybrid ranking](https://github.com/nexus69420/movie-recommender-streamlit/blob/main/app.py): Ranking boundary · Combines relevance and personalized predictions, then keeps five. · `app.py`
- [Recommendation display](https://github.com/nexus69420/movie-recommender-streamlit/blob/main/app.py): UI output · Renders five titles and their posters. · `app.py`

### External data & APIs

- **TMDB metadata**: Movie metadata source · Provides attributes used for content similarity.
- **MovieLens ratings**: Ratings dataset · Provides user-rating patterns for collaborative filtering.
- **OMDb poster API**: External API · Fetches poster imagery for displayed movies.

## Connections

- TMDB metadata → Training workflow: metadata
- MovieLens ratings → Training workflow: ratings
- Training workflow → Content similarity model: builds
- Training workflow → Surprise SVD model: trains
- Streamlit application → Movie and user input: collects
- Movie and user input → Content candidate scoring: selected movie
- Content similarity model → Content candidate scoring: similarity
- Content candidate scoring → Collaborative prediction: candidates
- Surprise SVD model → Collaborative prediction: predictions
- Collaborative prediction → Hybrid ranking: user scores
- Content candidate scoring → Hybrid ranking: relevance
- Hybrid ranking → Recommendation display: five movies
- OMDb poster API → Recommendation display: posters