# shu0209/movie_recommendation architecture

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

- Interactive diagram: https://gitdiagram.com/shu0209/movie_recommendation
- Repository: https://github.com/shu0209/movie_recommendation

## Overview

CineMatch is a Streamlit movie-discovery interface backed by a FastAPI service. Users can search titles and series, look up movie details, or request similar-movie recommendations; the backend combines local TF-IDF data with optional OMDB metadata. The graph preserves these distinct capabilities and the local recommendation-data layer. Source excerpts show the UI’s API helper and backend behavior, but omit some UI request details, so those links are limited to the documented frontend/backend relationship.

Main entry points: [`main.py`](https://github.com/shu0209/movie_recommendation/blob/main/main.py) (FastAPI routes), [`ui.py`](https://github.com/shu0209/movie_recommendation/blob/main/ui.py) (Streamlit UI), [`indices.pkl`](https://github.com/shu0209/movie_recommendation/blob/main/indices.pkl) (Title index), [`df.pkl`](https://github.com/shu0209/movie_recommendation/blob/main/df.pkl) (Movie records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["User Interface"]
  node_streamlit["Streamlit UI<br/>[ui.py]"]
  node_api_client["HTTP API helper<br/>[ui.py]"]
  node_search_ui["Search interface<br/>[ui.py]"]
  node_lookup_ui["Detail lookup<br/>[ui.py]"]
  node_recommend_ui["Recommendation view<br/>[ui.py]"]
end

subgraph group_service["API Service"]
  node_fastapi["FastAPI routes<br/>[main.py]"]
  node_search_endpoint["Movie search<br/>[main.py]"]
  node_lookup_endpoint["Movie lookup<br/>[main.py]"]
  node_bundle_endpoint["Bundle recommendations<br/>[main.py]"]
  node_tfidf_endpoint["TF-IDF endpoint<br/>[main.py]"]
end

subgraph group_recommendations["Recommendations"]
  node_tfidf_engine["Similarity scoring<br/>[main.py]"]
  node_title_index[("Title index<br/>[indices.pkl]")]
  node_movie_data[("Movie records<br/>[df.pkl]")]
  node_tfidf_matrix[("TF-IDF matrix<br/>[tfidf_metrix.pkl]")]
  node_tfidf_model[("TF-IDF model<br/>[tfidf.pkl]")]
end

subgraph group_metadata["Movie Metadata"]
  node_omdb_client["OMDB request client<br/>[main.py]"]
  node_omdb_service["OMDB API"]
  node_omdb_parsers["OMDB response parsing<br/>[main.py]"]
end

node_user(("Movie seeker"))

node_user -->|"uses"| node_streamlit
node_streamlit -->|"offers search"| node_search_ui
node_streamlit -->|"offers lookup"| node_lookup_ui
node_streamlit -->|"offers recommendations"| node_recommend_ui
node_search_ui -->|"requests search"| node_api_client
node_lookup_ui -->|"requests details"| node_api_client
node_recommend_ui -.->|"requests recommendations"| node_api_client
node_api_client -->|"sends HTTP"| node_fastapi
node_fastapi -->|"routes search"| node_search_endpoint
node_fastapi -->|"routes lookup"| node_lookup_endpoint
node_fastapi -->|"routes bundle"| node_bundle_endpoint
node_fastapi -->|"routes TF-IDF"| node_tfidf_endpoint
node_search_endpoint -->|"queries OMDB"| node_omdb_client
node_lookup_endpoint -->|"queries OMDB"| node_omdb_client
node_bundle_endpoint -->|"fetches details"| node_omdb_client
node_tfidf_endpoint -->|"scores titles"| node_tfidf_engine
node_bundle_endpoint -->|"scores titles"| node_tfidf_engine
node_bundle_endpoint -->|"enriches results"| node_omdb_client
node_omdb_client -->|"calls API"| node_omdb_service
node_omdb_client -->|"parses responses"| node_omdb_parsers
node_tfidf_engine -->|"reads index"| node_title_index
node_tfidf_engine -->|"reads titles"| node_movie_data
node_tfidf_engine -->|"scores vectors"| node_tfidf_matrix
node_fastapi -->|"loads model"| node_tfidf_model

click node_streamlit "https://github.com/shu0209/movie_recommendation/blob/main/ui.py"
click node_api_client "https://github.com/shu0209/movie_recommendation/blob/main/ui.py"
click node_search_ui "https://github.com/shu0209/movie_recommendation/blob/main/ui.py"
click node_lookup_ui "https://github.com/shu0209/movie_recommendation/blob/main/ui.py"
click node_recommend_ui "https://github.com/shu0209/movie_recommendation/blob/main/ui.py"
click node_fastapi "https://github.com/shu0209/movie_recommendation/blob/main/main.py"
click node_search_endpoint "https://github.com/shu0209/movie_recommendation/blob/main/main.py"
click node_lookup_endpoint "https://github.com/shu0209/movie_recommendation/blob/main/main.py"
click node_bundle_endpoint "https://github.com/shu0209/movie_recommendation/blob/main/main.py"
click node_tfidf_endpoint "https://github.com/shu0209/movie_recommendation/blob/main/main.py"
click node_omdb_client "https://github.com/shu0209/movie_recommendation/blob/main/main.py"
click node_omdb_parsers "https://github.com/shu0209/movie_recommendation/blob/main/main.py"
click node_tfidf_engine "https://github.com/shu0209/movie_recommendation/blob/main/main.py"
click node_title_index "https://github.com/shu0209/movie_recommendation/blob/main/indices.pkl"
click node_movie_data "https://github.com/shu0209/movie_recommendation/blob/main/df.pkl"
click node_tfidf_matrix "https://github.com/shu0209/movie_recommendation/blob/main/tfidf_metrix.pkl"
click node_tfidf_model "https://github.com/shu0209/movie_recommendation/blob/main/tfidf.pkl"

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_streamlit,node_api_client,node_search_ui,node_lookup_ui,node_recommend_ui toneBlue
class node_fastapi,node_search_endpoint,node_lookup_endpoint,node_bundle_endpoint,node_tfidf_endpoint toneAmber
class node_tfidf_engine,node_title_index,node_movie_data,node_tfidf_matrix,node_tfidf_model toneMint
class node_omdb_client,node_omdb_service,node_omdb_parsers toneRose
class node_user toneIndigo
```

## Components

### User Interface

- [Streamlit UI](https://github.com/shu0209/movie_recommendation/blob/main/ui.py): `ui.py`
- [HTTP API helper](https://github.com/shu0209/movie_recommendation/blob/main/ui.py): `ui.py`
- [Search interface](https://github.com/shu0209/movie_recommendation/blob/main/ui.py): `ui.py`
- [Detail lookup](https://github.com/shu0209/movie_recommendation/blob/main/ui.py): `ui.py`
- [Recommendation view](https://github.com/shu0209/movie_recommendation/blob/main/ui.py): `ui.py`

### API Service

- [FastAPI routes](https://github.com/shu0209/movie_recommendation/blob/main/main.py): `main.py`
- [Movie search](https://github.com/shu0209/movie_recommendation/blob/main/main.py): `main.py`
- [Movie lookup](https://github.com/shu0209/movie_recommendation/blob/main/main.py): `main.py`
- [Bundle recommendations](https://github.com/shu0209/movie_recommendation/blob/main/main.py): `main.py`
- [TF-IDF endpoint](https://github.com/shu0209/movie_recommendation/blob/main/main.py): `main.py`

### Recommendations

- [Similarity scoring](https://github.com/shu0209/movie_recommendation/blob/main/main.py): `main.py`
- [Title index](https://github.com/shu0209/movie_recommendation/blob/main/indices.pkl): `indices.pkl`
- [Movie records](https://github.com/shu0209/movie_recommendation/blob/main/df.pkl): `df.pkl`
- [TF-IDF matrix](https://github.com/shu0209/movie_recommendation/blob/main/tfidf_metrix.pkl): `tfidf_metrix.pkl`
- [TF-IDF model](https://github.com/shu0209/movie_recommendation/blob/main/tfidf.pkl): `tfidf.pkl`

### Movie Metadata

- [OMDB request client](https://github.com/shu0209/movie_recommendation/blob/main/main.py): `main.py`
- **OMDB API**
- [OMDB response parsing](https://github.com/shu0209/movie_recommendation/blob/main/main.py): `main.py`

### Other components

- **Movie seeker**

## Connections

- Movie seeker → Streamlit UI: uses (evidence: `README.md`)
- Streamlit UI → Search interface: offers search (evidence: `ui.py`)
- Streamlit UI → Detail lookup: offers lookup (evidence: `ui.py`)
- Streamlit UI → Recommendation view: offers recommendations (evidence: `ui.py`)
- Search interface → HTTP API helper: requests search (evidence: `ui.py`)
- Detail lookup → HTTP API helper: requests details (evidence: `ui.py`)
- Recommendation view → HTTP API helper: requests recommendations (evidence: `ui.py`)
- HTTP API helper → FastAPI routes: sends HTTP (evidence: `README.md`)
- FastAPI routes → Movie search: routes search (evidence: `main.py`)
- FastAPI routes → Movie lookup: routes lookup (evidence: `main.py`)
- FastAPI routes → Bundle recommendations: routes bundle (evidence: `main.py`)
- FastAPI routes → TF-IDF endpoint: routes TF-IDF (evidence: `main.py`)
- Movie search → OMDB request client: queries OMDB (evidence: `main.py`)
- Movie lookup → OMDB request client: queries OMDB (evidence: `main.py`)
- Bundle recommendations → OMDB request client: fetches details (evidence: `main.py`)
- TF-IDF endpoint → Similarity scoring: scores titles (evidence: `main.py`)
- Bundle recommendations → Similarity scoring: scores titles (evidence: `main.py`)
- Bundle recommendations → OMDB request client: enriches results (evidence: `main.py`)
- OMDB request client → OMDB API: calls API (evidence: `main.py`)
- OMDB request client → OMDB response parsing: parses responses (evidence: `main.py`)
- Similarity scoring → Title index: reads index (evidence: `main.py`)
- Similarity scoring → Movie records: reads titles (evidence: `main.py`)
- Similarity scoring → TF-IDF matrix: scores vectors (evidence: `main.py`)
- FastAPI routes → TF-IDF model: loads model (evidence: `main.py`)
