# karthikesh-ui/ai-movie-recommendation-system architecture

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

- Interactive diagram: https://gitdiagram.com/karthikesh-ui/ai-movie-recommendation-system
- Repository: https://github.com/karthikesh-ui/ai-movie-recommendation-system

## Overview

MovieAI serves Indian-movie search, title-based recommendations, natural-language recommendations, and separate discovery/enrichment capabilities. The main recommendation path validates user intent, filters and ranks the local catalog, then optionally enriches selected results; Gemini does not choose recommendations. Hybrid retrieval and Watchmode discovery add provider-backed results and verified availability separately. Edges reflect README-described flows and sampled imports/calls; unsampled frontend-to-API wiring is not asserted.

Main entry points: [`backend/app.py`](https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/app.py) (HTTP API), [`frontend/app.js`](https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/frontend/app.js) (Movie web UI), [`backend/nl_pipeline.py`](https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/nl_pipeline.py) (NL recommendation flow), [`backend/hybrid_retrieval.py`](https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/hybrid_retrieval.py) (Hybrid retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["Movie web UI<br/>[app.js]"]
  node_search_ui["Search and autocomplete<br/>[movie-search.js]"]
  node_details_ui["Movie details<br/>[movie-details.js]"]
  node_recommend_ui["Recommendation results<br/>[recommendation.js]"]
end

subgraph group_api["API orchestration"]
  node_api_app["HTTP API<br/>[app.py]"]
end

subgraph group_recommendation["Local recommendations"]
  node_local_catalog[("Indian movie catalog")]
  node_title_recs["Title similarity<br/>[app.py]"]
  node_intent_parser["Gemini intent parsing<br/>[app.py]"]
  node_intent_validation["Intent validation<br/>[nl_intent.py]"]
  node_candidate_retrieval["Filtered retrieval<br/>[nl_recommender.py]"]
  node_ranking["Deterministic ranking<br/>[nl_ranking.py]"]
  node_nl_pipeline["NL recommendation flow<br/>[nl_pipeline.py]"]
  node_explanation["Grounded explanations<br/>[app.py]"]
  node_hybrid["Hybrid retrieval"]
  node_candidate_model["Normalized candidates<br/>[movie_candidate.py]"]
end

subgraph group_providers["External providers"]
  node_omdb["OMDb enrichment<br/>[app.py]"]
  node_watchmode_client["Watchmode client"]
  node_discovery["Live release discovery"]
  node_tmdb_client["TMDB discovery client<br/>[tmdb_client.py]"]
  node_gemini{{"Gemini service"}}
  node_omdb_service{{"OMDb service"}}
  node_watchmode_service{{"Watchmode service"}}
  node_tmdb_service{{"TMDB service"}}
end

node_user(("Movie seeker"))

node_user -->|"uses"| node_web
node_web -->|"includes"| node_search_ui
node_web -->|"includes"| node_details_ui
node_web -->|"includes"| node_recommend_ui
node_user -->|"requests"| node_api_app
node_api_app -->|"reads"| node_local_catalog
node_api_app -->|"routes recommendations"| node_title_recs
node_api_app -->|"parses request"| node_intent_parser
node_intent_parser -->|"requests intent"| node_gemini
node_api_app -->|"validates intent"| node_intent_validation
node_api_app -->|"runs recommendations"| node_nl_pipeline
node_nl_pipeline -->|"retrieves candidates"| node_candidate_retrieval
node_nl_pipeline -->|"ranks candidates"| node_ranking
node_candidate_retrieval -->|"filters"| node_local_catalog
node_api_app -->|"assembles explanations"| node_explanation
node_api_app -->|"enriches results"| node_omdb
node_omdb -->|"requests metadata"| node_omdb_service
node_api_app -->|"routes hybrid requests"| node_hybrid
node_hybrid -->|"normalizes results"| node_candidate_model
node_hybrid -->|"checks availability"| node_watchmode_client
node_watchmode_client -->|"calls API"| node_watchmode_service
node_api_app -->|"routes discovery"| node_discovery
node_discovery -->|"fetches releases"| node_watchmode_client
node_api_app -->|"uses discovery client"| node_tmdb_client
node_tmdb_client -->|"calls API"| node_tmdb_service

click node_web "https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/frontend/app.js"
click node_search_ui "https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/frontend/movie-search.js"
click node_details_ui "https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/frontend/movie-details.js"
click node_recommend_ui "https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/frontend/recommendation.js"
click node_api_app "https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/app.py"
click node_local_catalog "https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/data/processed/indian_movies_clean.csv"
click node_title_recs "https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/app.py"
click node_intent_parser "https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/app.py"
click node_intent_validation "https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/nl_intent.py"
click node_candidate_retrieval "https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/nl_recommender.py"
click node_ranking "https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/nl_ranking.py"
click node_nl_pipeline "https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/nl_pipeline.py"
click node_explanation "https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/app.py"
click node_hybrid "https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/hybrid_retrieval.py"
click node_candidate_model "https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/movie_candidate.py"
click node_omdb "https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/app.py"
click node_watchmode_client "https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/watchmode_client.py"
click node_discovery "https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/discovery_provider.py"
click node_tmdb_client "https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/tmdb_client.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_web,node_search_ui,node_details_ui,node_recommend_ui toneBlue
class node_api_app toneAmber
class node_local_catalog,node_title_recs,node_intent_parser,node_intent_validation,node_candidate_retrieval,node_ranking,node_nl_pipeline,node_explanation,node_hybrid,node_candidate_model toneMint
class node_omdb,node_watchmode_client,node_discovery,node_tmdb_client,node_gemini,node_omdb_service,node_watchmode_service,node_tmdb_service toneRose
class node_user toneIndigo
```

## Components

### User experience

- [Movie web UI](https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/frontend/app.js): `frontend/app.js`
- [Search and autocomplete](https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/frontend/movie-search.js): `frontend/movie-search.js`
- [Movie details](https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/frontend/movie-details.js): `frontend/movie-details.js`
- [Recommendation results](https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/frontend/recommendation.js): `frontend/recommendation.js`

### API orchestration

- [HTTP API](https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/app.py): `backend/app.py`

### Local recommendations

- [Indian movie catalog](https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/data/processed/indian_movies_clean.csv): `data/processed/indian_movies_clean.csv`
- [Title similarity](https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/app.py): `backend/app.py`
- [Gemini intent parsing](https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/app.py): `backend/app.py`
- [Intent validation](https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/nl_intent.py): `backend/nl_intent.py`
- [Filtered retrieval](https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/nl_recommender.py): `backend/nl_recommender.py`
- [Deterministic ranking](https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/nl_ranking.py): `backend/nl_ranking.py`
- [NL recommendation flow](https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/nl_pipeline.py): `backend/nl_pipeline.py`
- [Grounded explanations](https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/app.py): `backend/app.py`
- [Hybrid retrieval](https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/hybrid_retrieval.py): `backend/hybrid_retrieval.py`
- [Normalized candidates](https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/movie_candidate.py): `backend/movie_candidate.py`

### External providers

- [OMDb enrichment](https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/app.py): `backend/app.py`
- [Watchmode client](https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/watchmode_client.py): `backend/watchmode_client.py`
- [Live release discovery](https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/discovery_provider.py): `backend/discovery_provider.py`
- [TMDB discovery client](https://github.com/karthikesh-ui/ai-movie-recommendation-system/blob/main/backend/tmdb_client.py): `backend/tmdb_client.py`
- **Gemini service**
- **OMDb service**
- **Watchmode service**
- **TMDB service**

### Other components

- **Movie seeker**

## Connections

- Movie seeker → Movie web UI: uses (evidence: `README.md`)
- Movie web UI → Search and autocomplete: includes
- Movie web UI → Movie details: includes
- Movie web UI → Recommendation results: includes
- Movie seeker → HTTP API: requests (evidence: `README.md`)
- HTTP API → Indian movie catalog: reads (evidence: `README.md`)
- HTTP API → Title similarity: routes recommendations (evidence: `README.md`)
- HTTP API → Gemini intent parsing: parses request (evidence: `README.md`)
- Gemini intent parsing → Gemini service: requests intent (evidence: `README.md`)
- HTTP API → Intent validation: validates intent (evidence: `backend/app.py`)
- HTTP API → NL recommendation flow: runs recommendations (evidence: `backend/app.py`)
- NL recommendation flow → Filtered retrieval: retrieves candidates (evidence: `backend/nl_pipeline.py`)
- NL recommendation flow → Deterministic ranking: ranks candidates (evidence: `backend/nl_pipeline.py`)
- Filtered retrieval → Indian movie catalog: filters (evidence: `README.md`)
- HTTP API → Grounded explanations: assembles explanations (evidence: `README.md`)
- HTTP API → OMDb enrichment: enriches results (evidence: `backend/app.py`)
- OMDb enrichment → OMDb service: requests metadata (evidence: `backend/app.py`)
- HTTP API → Hybrid retrieval: routes hybrid requests (evidence: `backend/app.py`)
- Hybrid retrieval → Normalized candidates: normalizes results (evidence: `backend/hybrid_retrieval.py`)
- Hybrid retrieval → Watchmode client: checks availability (evidence: `backend/hybrid_retrieval.py`)
- Watchmode client → Watchmode service: calls API (evidence: `backend/watchmode_client.py`)
- HTTP API → Live release discovery: routes discovery (evidence: `backend/app.py`)
- Live release discovery → Watchmode client: fetches releases (evidence: `backend/discovery_provider.py`)
- HTTP API → TMDB discovery client: uses discovery client (evidence: `backend/app.py`)
- TMDB discovery client → TMDB service: calls API (evidence: `backend/tmdb_client.py`)
