# gayatri-oman/movie-recommendation-system architecture

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

- Interactive diagram: https://gitdiagram.com/gayatri-oman/movie-recommendation-system
- Repository: https://github.com/gayatri-oman/movie-recommendation-system

## Overview

This is a movie-discovery web app: users search by title, choose a match, and request content-based recommendations; the UI also loads featured movies. The Flask API delegates search and recommendation work to a Python engine built around a cleaned movie dataset, TF-IDF, and cosine similarity. It enriches recommendation and featured results with TMDB poster data. The README also describes responsive presentation and similarity percentages. The README contains conflicting versions, so the graph follows capabilities visible in the sampled code; unsampled preprocessing details are not expanded.

Main entry points: [`frontend/src/App.jsx`](https://github.com/gayatri-oman/movie-recommendation-system/blob/main/frontend/src/App.jsx) (Movie experience), [`backend/app.py`](https://github.com/gayatri-oman/movie-recommendation-system/blob/main/backend/app.py) (Flask routes), [`frontend/src/services/api.js`](https://github.com/gayatri-oman/movie-recommendation-system/blob/main/frontend/src/services/api.js) (API client), [`src/recommender.py`](https://github.com/gayatri-oman/movie-recommendation-system/blob/main/src/recommender.py) (Search and recommendations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["Movie experience<br/>[App.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_background["Cinematic background"]
end

subgraph group_api["REST API"]
  node_flask["Flask routes<br/>[app.py]"]
end

subgraph group_recommendation["Recommendation engine"]
  node_catalog[("Cleaned movie catalog<br/>[movies_cleaned.csv]")]
  node_engine["Search and recommendations<br/>[recommender.py]"]
end

subgraph group_enrichment["Poster enrichment"]
  node_tmdb_adapter["TMDB lookup<br/>[tmdb_service.py]"]
end

node_viewer(("Movie viewer"))
node_tmdb["TMDB service"]

node_viewer -->|"searches movies"| node_app
node_app -->|"requests search"| node_api_client
node_app -->|"requests recommendations"| node_api_client
node_app -->|"loads featured"| node_api_client
node_app -->|"renders"| node_background
node_api_client -->|"calls REST routes"| node_flask
node_flask -->|"delegates search"| node_engine
node_flask -->|"delegates ranking"| node_engine
node_engine -->|"loads dataset"| node_catalog
node_flask -->|"looks up posters"| node_tmdb_adapter
node_tmdb_adapter -->|"searches movies"| node_tmdb

click node_app "https://github.com/gayatri-oman/movie-recommendation-system/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/gayatri-oman/movie-recommendation-system/blob/main/frontend/src/services/api.js"
click node_background "https://github.com/gayatri-oman/movie-recommendation-system/blob/main/frontend/src/AnimatedBackground.jsx"
click node_flask "https://github.com/gayatri-oman/movie-recommendation-system/blob/main/backend/app.py"
click node_catalog "https://github.com/gayatri-oman/movie-recommendation-system/blob/main/data/movies_cleaned.csv"
click node_engine "https://github.com/gayatri-oman/movie-recommendation-system/blob/main/src/recommender.py"
click node_tmdb_adapter "https://github.com/gayatri-oman/movie-recommendation-system/blob/main/backend/tmdb_service.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_app,node_api_client,node_background,node_viewer toneBlue
class node_flask toneAmber
class node_catalog,node_engine toneMint
class node_tmdb_adapter toneRose
class node_tmdb toneIndigo
```

## Components

### Web client

- [Movie experience](https://github.com/gayatri-oman/movie-recommendation-system/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/gayatri-oman/movie-recommendation-system/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Cinematic background](https://github.com/gayatri-oman/movie-recommendation-system/blob/main/frontend/src/AnimatedBackground.jsx): `frontend/src/AnimatedBackground.jsx`

### REST API

- [Flask routes](https://github.com/gayatri-oman/movie-recommendation-system/blob/main/backend/app.py): `backend/app.py`

### Recommendation engine

- [Cleaned movie catalog](https://github.com/gayatri-oman/movie-recommendation-system/blob/main/data/movies_cleaned.csv): `data/movies_cleaned.csv`
- [Search and recommendations](https://github.com/gayatri-oman/movie-recommendation-system/blob/main/src/recommender.py): `src/recommender.py`

### Poster enrichment

- [TMDB lookup](https://github.com/gayatri-oman/movie-recommendation-system/blob/main/backend/tmdb_service.py): `backend/tmdb_service.py`

### Other components

- **Movie viewer**
- **TMDB service**

## Connections

- Movie viewer → Movie experience: searches movies (evidence: `frontend/src/App.jsx`)
- Movie experience → API client: requests search (evidence: `frontend/src/App.jsx`)
- Movie experience → API client: requests recommendations (evidence: `frontend/src/App.jsx`)
- Movie experience → API client: loads featured (evidence: `frontend/src/App.jsx`)
- Movie experience → Cinematic background: renders (evidence: `frontend/src/App.jsx`)
- API client → Flask routes: calls REST routes (evidence: `frontend/src/services/api.js`)
- Flask routes → Search and recommendations: delegates search (evidence: `backend/app.py`)
- Flask routes → Search and recommendations: delegates ranking (evidence: `backend/app.py`)
- Search and recommendations → Cleaned movie catalog: loads dataset (evidence: `src/recommender.py`)
- Flask routes → TMDB lookup: looks up posters (evidence: `backend/app.py`)
- TMDB lookup → TMDB service: searches movies (evidence: `backend/tmdb_service.py`)