# tayyabsiddique77/semantic_movie_recommender architecture

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

- Interactive diagram: https://gitdiagram.com/tayyabsiddique77/semantic_movie_recommender
- Repository: https://github.com/tayyabsiddique77/semantic_movie_recommender

## Overview

CineMatch is a Streamlit semantic movie recommender: a user selects a title, the app retrieves its stored embedding, searches a FAISS index, and displays similar movies with posters fetched from TMDB. The README also describes the offline metadata-cleaning and embedding-generation pipeline, but its notebook and source dataset are absent from the supplied tree, so those implementation stages are not represented as runtime components.

Main entry points: [`app.py`](https://github.com/tayyabsiddique77/semantic_movie_recommender/blob/main/app.py) (Recommendation search), [`movies.pkl`](https://github.com/tayyabsiddique77/semantic_movie_recommender/blob/main/movies.pkl) (Movie catalog), [`embeddings.pkl`](https://github.com/tayyabsiddique77/semantic_movie_recommender/blob/main/embeddings.pkl) (Movie embeddings), [`movie_index.faiss`](https://github.com/tayyabsiddique77/semantic_movie_recommender/blob/main/movie_index.faiss) (FAISS index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_streamlit["Movie selection UI<br/>[app.py]"]
  node_results["Recommendation display<br/>[app.py]"]
end

subgraph group_recommendation["Recommendation"]
  node_recommend["Recommendation search<br/>[app.py]"]
end

subgraph group_artifacts["Stored artifacts"]
  node_catalog["Movie catalog<br/>[movies.pkl]"]
  node_embeddings["Movie embeddings<br/>[embeddings.pkl]"]
  node_faiss[("FAISS index<br/>[movie_index.faiss]")]
end

subgraph group_integration["Poster integration"]
  node_poster["Poster retrieval<br/>[app.py]"]
end

node_user(("Movie seeker"))
node_tmdb["TMDB API"]

node_user -->|"selects title"| node_streamlit
node_streamlit -->|"invokes search"| node_recommend
node_recommend -->|"looks up movie"| node_catalog
node_recommend -->|"reads vector"| node_embeddings
node_recommend -->|"searches neighbors"| node_faiss
node_recommend -->|"fetches posters"| node_poster
node_poster -->|"requests poster data"| node_tmdb
node_recommend -->|"returns recommendations"| node_results
node_results -->|"displays results"| node_user

click node_streamlit "https://github.com/tayyabsiddique77/semantic_movie_recommender/blob/main/app.py"
click node_recommend "https://github.com/tayyabsiddique77/semantic_movie_recommender/blob/main/app.py"
click node_catalog "https://github.com/tayyabsiddique77/semantic_movie_recommender/blob/main/movies.pkl"
click node_embeddings "https://github.com/tayyabsiddique77/semantic_movie_recommender/blob/main/embeddings.pkl"
click node_faiss "https://github.com/tayyabsiddique77/semantic_movie_recommender/blob/main/movie_index.faiss"
click node_poster "https://github.com/tayyabsiddique77/semantic_movie_recommender/blob/main/app.py"
click node_results "https://github.com/tayyabsiddique77/semantic_movie_recommender/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_streamlit,node_results toneBlue
class node_recommend toneAmber
class node_catalog,node_embeddings,node_faiss,node_tmdb toneMint
class node_poster toneRose
class node_user toneIndigo
```

## Components

### User interface

- [Movie selection UI](https://github.com/tayyabsiddique77/semantic_movie_recommender/blob/main/app.py): `app.py`
- [Recommendation display](https://github.com/tayyabsiddique77/semantic_movie_recommender/blob/main/app.py): `app.py`

### Recommendation

- [Recommendation search](https://github.com/tayyabsiddique77/semantic_movie_recommender/blob/main/app.py): `app.py`

### Stored artifacts

- [Movie catalog](https://github.com/tayyabsiddique77/semantic_movie_recommender/blob/main/movies.pkl): `movies.pkl`
- [Movie embeddings](https://github.com/tayyabsiddique77/semantic_movie_recommender/blob/main/embeddings.pkl): `embeddings.pkl`
- [FAISS index](https://github.com/tayyabsiddique77/semantic_movie_recommender/blob/main/movie_index.faiss): `movie_index.faiss`

### Poster integration

- [Poster retrieval](https://github.com/tayyabsiddique77/semantic_movie_recommender/blob/main/app.py): `app.py`

### Other components

- **Movie seeker**
- **TMDB API**

## Connections

- Movie seeker → Movie selection UI: selects title (evidence: `README.md`)
- Movie selection UI → Recommendation search: invokes search (evidence: `app.py`)
- Recommendation search → Movie catalog: looks up movie (evidence: `app.py`)
- Recommendation search → Movie embeddings: reads vector (evidence: `app.py`)
- Recommendation search → FAISS index: searches neighbors (evidence: `app.py`)
- Recommendation search → Poster retrieval: fetches posters (evidence: `app.py`)
- Poster retrieval → TMDB API: requests poster data (evidence: `app.py`)
- Recommendation search → Recommendation display: returns recommendations (evidence: `app.py`)
- Recommendation display → Movie seeker: displays results (evidence: `README.md`)