# subhamgupta9/cinematch-ai architecture

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

- Interactive diagram: https://gitdiagram.com/subhamgupta9/cinematch-ai
- Repository: https://github.com/subhamgupta9/cinematch-ai

## Overview

CineMatch AI is a Streamlit movie-recommendation and global-discovery application. Users navigate to discovery, search by taste or a movie, browse by genre and region or ratings, and receive recommendations or movie details. The documented hybrid path combines local content and collaborative signals with global TMDb discovery; details include cast, trailers and India streaming options. The graph preserves the documented watchlist and history capabilities. Some subsystem links reflect README-level architecture because their implementation was not sampled.

Main entry points: [`app.py`](https://github.com/subhamgupta9/cinematch-ai/blob/main/app.py) (Streamlit app), [`hybrid_recommender.py`](https://github.com/subhamgupta9/cinematch-ai/blob/main/hybrid_recommender.py) (Hybrid recommender), [`tmdb_client.py`](https://github.com/subhamgupta9/cinematch-ai/blob/main/tmdb_client.py) (Movie metadata client), [`ui/page_discover.py`](https://github.com/subhamgupta9/cinematch-ai/blob/main/ui/page_discover.py) (Discover studio)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_app["Streamlit app<br/>[app.py]"]
  node_navigation["Navigation and state<br/>[components.py]"]
  node_discover_ui["Discover studio<br/>[page_discover.py]"]
  node_details["Movie details"]
  node_theme["Accessible theme<br/>[styles.py]"]
end

subgraph group_discovery["Recommendation and discovery"]
  node_hybrid["Hybrid recommender"]
  node_candidates["Candidate generation"]
end

subgraph group_catalog["Catalog and metadata"]
  node_global_search["Global search<br/>[tmdb_search.py]"]
  node_metadata["Movie metadata client<br/>[tmdb_client.py]"]
  node_unified["Unified movie records"]
  node_movielens[("MovieLens catalog and ratings")]
end

subgraph group_models["Recommendation models"]
  node_content["Content similarity<br/>[recommender.py]"]
  node_collaborative["Collaborative filtering"]
end

node_user(("Viewer"))
node_tmdb{{"TMDb API"}}
node_justwatch{{"JustWatch availability"}}
node_youtube{{"YouTube trailers"}}

node_user -->|"interacts with"| node_app
node_app -->|"renders navigation"| node_navigation
node_app -->|"routes to discovery"| node_discover_ui
node_app -->|"renders details"| node_details
node_app -->|"applies styles"| node_theme
node_discover_ui -->|"requests recommendations"| node_hybrid
node_discover_ui -->|"searches titles"| node_global_search
node_discover_ui -->|"fetches discovery results"| node_metadata
node_hybrid -->|"builds candidate pool"| node_candidates
node_hybrid -->|"scores content"| node_content
node_hybrid -->|"uses affinity"| node_collaborative
node_hybrid -->|"adds global candidates"| node_global_search
node_candidates -->|"normalizes movies"| node_unified
node_candidates -.->|"reads catalog data"| node_movielens
node_collaborative -.->|"fits rating data"| node_movielens
node_global_search -->|"searches catalog"| node_tmdb
node_metadata -->|"fetches movie details"| node_tmdb
node_metadata -->|"gets watch providers"| node_justwatch
node_metadata -->|"provides trailer links"| node_youtube
node_details -->|"loads rich details"| node_metadata
node_navigation -.->|"tracks navigation state"| node_app

click node_app "https://github.com/subhamgupta9/cinematch-ai/blob/main/app.py"
click node_navigation "https://github.com/subhamgupta9/cinematch-ai/blob/main/ui/components.py"
click node_discover_ui "https://github.com/subhamgupta9/cinematch-ai/blob/main/ui/page_discover.py"
click node_details "https://github.com/subhamgupta9/cinematch-ai/blob/main/ui/modal_movie_details.py"
click node_theme "https://github.com/subhamgupta9/cinematch-ai/blob/main/ui/styles.py"
click node_hybrid "https://github.com/subhamgupta9/cinematch-ai/blob/main/hybrid_recommender.py"
click node_candidates "https://github.com/subhamgupta9/cinematch-ai/blob/main/candidate_generator.py"
click node_global_search "https://github.com/subhamgupta9/cinematch-ai/blob/main/tmdb_search.py"
click node_metadata "https://github.com/subhamgupta9/cinematch-ai/blob/main/tmdb_client.py"
click node_unified "https://github.com/subhamgupta9/cinematch-ai/blob/main/unified_data_model.py"
click node_content "https://github.com/subhamgupta9/cinematch-ai/blob/main/recommender.py"
click node_collaborative "https://github.com/subhamgupta9/cinematch-ai/blob/main/collaborative_recommender.py"
click node_movielens "https://github.com/subhamgupta9/cinematch-ai/tree/main/data/ml-latest-small"

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_app,node_navigation,node_discover_ui,node_details,node_theme,node_user toneBlue
class node_hybrid,node_candidates toneAmber
class node_global_search,node_metadata,node_unified,node_movielens,node_tmdb toneMint
class node_content,node_collaborative toneRose
class node_justwatch,node_youtube toneIndigo
```

## Components

### User experience

- [Streamlit app](https://github.com/subhamgupta9/cinematch-ai/blob/main/app.py): `app.py`
- [Navigation and state](https://github.com/subhamgupta9/cinematch-ai/blob/main/ui/components.py): `ui/components.py`
- [Discover studio](https://github.com/subhamgupta9/cinematch-ai/blob/main/ui/page_discover.py): `ui/page_discover.py`
- [Movie details](https://github.com/subhamgupta9/cinematch-ai/blob/main/ui/modal_movie_details.py): `ui/modal_movie_details.py`
- [Accessible theme](https://github.com/subhamgupta9/cinematch-ai/blob/main/ui/styles.py): `ui/styles.py`

### Recommendation and discovery

- [Hybrid recommender](https://github.com/subhamgupta9/cinematch-ai/blob/main/hybrid_recommender.py): `hybrid_recommender.py`
- [Candidate generation](https://github.com/subhamgupta9/cinematch-ai/blob/main/candidate_generator.py): `candidate_generator.py`

### Catalog and metadata

- [Global search](https://github.com/subhamgupta9/cinematch-ai/blob/main/tmdb_search.py): `tmdb_search.py`
- [Movie metadata client](https://github.com/subhamgupta9/cinematch-ai/blob/main/tmdb_client.py): `tmdb_client.py`
- [Unified movie records](https://github.com/subhamgupta9/cinematch-ai/blob/main/unified_data_model.py): `unified_data_model.py`
- [MovieLens catalog and ratings](https://github.com/subhamgupta9/cinematch-ai/tree/main/data/ml-latest-small): `data/ml-latest-small`

### Recommendation models

- [Content similarity](https://github.com/subhamgupta9/cinematch-ai/blob/main/recommender.py): `recommender.py`
- [Collaborative filtering](https://github.com/subhamgupta9/cinematch-ai/blob/main/collaborative_recommender.py): `collaborative_recommender.py`

### Other components

- **Viewer**
- **TMDb API**
- **JustWatch availability**
- **YouTube trailers**

## Connections

- Viewer → Streamlit app: interacts with (evidence: `README.md`)
- Streamlit app → Navigation and state: renders navigation (evidence: `app.py`)
- Streamlit app → Discover studio: routes to discovery (evidence: `app.py`)
- Streamlit app → Movie details: renders details (evidence: `app.py`)
- Streamlit app → Accessible theme: applies styles (evidence: `README.md`)
- Discover studio → Hybrid recommender: requests recommendations (evidence: `README.md`)
- Discover studio → Global search: searches titles (evidence: `ui/page_discover.py`)
- Discover studio → Movie metadata client: fetches discovery results (evidence: `app.py`)
- Hybrid recommender → Candidate generation: builds candidate pool (evidence: `hybrid_recommender.py`)
- Hybrid recommender → Content similarity: scores content (evidence: `README.md`)
- Hybrid recommender → Collaborative filtering: uses affinity (evidence: `README.md`)
- Hybrid recommender → Global search: adds global candidates (evidence: `README.md`)
- Candidate generation → Unified movie records: normalizes movies (evidence: `candidate_generator.py`)
- Candidate generation → MovieLens catalog and ratings: reads catalog data
- Collaborative filtering → MovieLens catalog and ratings: fits rating data
- Global search → TMDb API: searches catalog (evidence: `README.md`)
- Movie metadata client → TMDb API: fetches movie details (evidence: `README.md`)
- Movie metadata client → JustWatch availability: gets watch providers (evidence: `README.md`)
- Movie metadata client → YouTube trailers: provides trailer links (evidence: `README.md`)
- Movie details → Movie metadata client: loads rich details (evidence: `ui/modal_movie_details.py`)
- Navigation and state → Streamlit app: tracks navigation state (evidence: `app.py`)
