# hemanthvnp/cinescope architecture

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

- Interactive diagram: https://gitdiagram.com/hemanthvnp/cinescope
- Repository: https://github.com/hemanthvnp/cinescope

## Overview

CineScope is a movie discovery and recommendation platform. Users browse and search in the React app, which calls the API gateway; recommendations can come from the ML service, with documented genre-service and TMDB fallbacks. A separate natural-language query workflow classifies queries, plans and executes service tools, then aggregates results and optional provider data. The graph also preserves profile/watchlist features and the standalone clustering capability. Several connections are documented in the README; unsampled modules are represented only where the tree or documentation supports their role.

Main entry points: [`backend/src/app.js`](https://github.com/hemanthvnp/cinescope/blob/main/backend/src/app.js) (Gateway routes), [`services/ml-service/recommender/hybrid.py`](https://github.com/hemanthvnp/cinescope/blob/main/services/ml-service/recommender/hybrid.py) (Hybrid recommender), [`services/ai-orchestration/app.py`](https://github.com/hemanthvnp/cinescope/blob/main/services/ai-orchestration/app.py) (Query endpoint), [`frontend/src/App.jsx`](https://github.com/hemanthvnp/cinescope/blob/main/frontend/src/App.jsx) (React app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web app"]
  node_spa["React app<br/>[App.jsx]"]
  node_search["Search pages<br/>[SearchPage.jsx]"]
  node_queryui["Query Lab<br/>[QueryLab.jsx]"]
  node_queryapi["Query API client<br/>[query.js]"]
  node_searchfilters["Search filters"]
  node_axios["HTTP client<br/>[axios.js]"]
end

subgraph group_gateway["API gateway"]
  node_gatewayapp["Gateway routes<br/>[app.js]"]
  node_auth["Authentication<br/>[authMiddleware.js]"]
  node_userctrl["User accounts<br/>[userController.js]"]
  node_moviectrl["Movie search<br/>[movieController.js]"]
  node_ratingctrl["Ratings"]
  node_watchlist["Watchlist API<br/>[watchlistRoutes.js]"]
  node_tmdbgateway["TMDB gateway<br/>[tmdbService.js]"]
  node_email["Email OTP<br/>[emailService.js]"]
end

subgraph group_fallback["Genre fallback"]
  node_genreapi["Recommendation API"]
  node_genresvc["Genre recommender"]
  node_genredata[("Preference stores<br/>[UserPreference.js]")]
  node_genredb[("Mongo connection<br/>[db.js]")]
  node_genretmdb["TMDB client<br/>[tmdbClient.js]"]
end

subgraph group_ml["ML recommendations"]
  node_mlapi["ML API<br/>[app.py]"]
  node_hybrid["Hybrid recommender<br/>[hybrid.py]"]
  node_collab["Collaborative model<br/>[collaborative.py]"]
  node_content["Content model<br/>[content_based.py]"]
  node_explainer["Recommendation explanations<br/>[explainer.py]"]
  node_mlstorage["ML data access<br/>[database.py]"]
  node_mltmdb["ML TMDB client<br/>[tmdb_client.py]"]
  node_clustering["Movie clustering<br/>[api.py]"]
end

subgraph group_ai["AI query"]
  node_queryservice["Query endpoint<br/>[app.py]"]
  node_querymodel["Query and filters<br/>[query.py]"]
  node_classifier["Intent classifier"]
  node_planner["Tool planner<br/>[tool_planner.py]"]
  node_engine["Execution engine"]
  node_cache[("Tool cache<br/>[semantic_cache.py]")]
end

node_viewer(("Movie viewer"))

node_viewer -->|"uses"| node_spa
node_spa -->|"routes to"| node_search
node_spa -->|"routes to"| node_queryui
node_search -->|"uses filters"| node_searchfilters
node_queryui -->|"submits query"| node_queryapi
node_queryapi -->|"posts via"| node_axios
node_axios -->|"calls gateway"| node_gatewayapp
node_gatewayapp -.->|"protects routes"| node_auth
node_gatewayapp -->|"routes requests"| node_userctrl
node_gatewayapp -->|"routes requests"| node_moviectrl
node_gatewayapp -->|"routes requests"| node_ratingctrl
node_gatewayapp -.->|"mounts routes"| node_watchlist
node_moviectrl -->|"fetches movies"| node_tmdbgateway
node_userctrl -->|"sends OTP"| node_email
node_userctrl -->|"syncs preferences"| node_genreapi
node_gatewayapp -.->|"requests recommendations"| node_mlapi
node_gatewayapp -.->|"fallback recommendations"| node_genreapi
node_gatewayapp -.->|"fallback trending"| node_tmdbgateway
node_genreapi -->|"delegates"| node_genresvc
node_genresvc -->|"reads and writes"| node_genredata
node_genresvc -->|"discovers candidates"| node_genretmdb
node_genredb -.->|"connects storage"| node_genredata
node_mlapi -->|"gets recommendations"| node_hybrid
node_hybrid -->|"uses content model"| node_content
node_hybrid -->|"uses collaborative model"| node_collab
node_hybrid -->|"generates explanations"| node_explainer
node_hybrid -->|"loads user data"| node_mlstorage
node_hybrid -->|"fetches movie data"| node_mltmdb
node_viewer -.->|"uses analysis"| node_clustering
node_queryservice -->|"validates request"| node_querymodel
node_queryservice -->|"classifies query"| node_classifier
node_queryservice -->|"plans tools"| node_planner
node_queryservice -->|"executes plan"| node_engine
node_engine -->|"checks and stores"| node_cache
node_queryservice -.->|"returns results"| node_viewer

click node_spa "https://github.com/hemanthvnp/cinescope/blob/main/frontend/src/App.jsx"
click node_search "https://github.com/hemanthvnp/cinescope/blob/main/frontend/src/pages/SearchPage.jsx"
click node_queryui "https://github.com/hemanthvnp/cinescope/blob/main/frontend/src/pages/QueryLab.jsx"
click node_queryapi "https://github.com/hemanthvnp/cinescope/blob/main/frontend/src/api/query.js"
click node_searchfilters "https://github.com/hemanthvnp/cinescope/blob/main/frontend/src/context/SearchFilterContext.jsx"
click node_axios "https://github.com/hemanthvnp/cinescope/blob/main/frontend/src/api/axios.js"
click node_gatewayapp "https://github.com/hemanthvnp/cinescope/blob/main/backend/src/app.js"
click node_auth "https://github.com/hemanthvnp/cinescope/blob/main/backend/src/middleware/authMiddleware.js"
click node_userctrl "https://github.com/hemanthvnp/cinescope/blob/main/backend/src/controllers/userController.js"
click node_moviectrl "https://github.com/hemanthvnp/cinescope/blob/main/backend/src/controllers/movieController.js"
click node_ratingctrl "https://github.com/hemanthvnp/cinescope/blob/main/backend/src/controllers/ratingController.js"
click node_watchlist "https://github.com/hemanthvnp/cinescope/blob/main/backend/src/routes/watchlistRoutes.js"
click node_tmdbgateway "https://github.com/hemanthvnp/cinescope/blob/main/backend/src/services/tmdbService.js"
click node_email "https://github.com/hemanthvnp/cinescope/blob/main/backend/src/services/emailService.js"
click node_genreapi "https://github.com/hemanthvnp/cinescope/blob/main/services/recommendation-service/src/controllers/recommendationController.js"
click node_genresvc "https://github.com/hemanthvnp/cinescope/blob/main/services/recommendation-service/src/services/recommendationService.js"
click node_genredata "https://github.com/hemanthvnp/cinescope/blob/main/services/recommendation-service/src/models/UserPreference.js"
click node_genredb "https://github.com/hemanthvnp/cinescope/blob/main/services/recommendation-service/src/config/db.js"
click node_genretmdb "https://github.com/hemanthvnp/cinescope/blob/main/services/recommendation-service/src/services/tmdbClient.js"
click node_mlapi "https://github.com/hemanthvnp/cinescope/blob/main/services/ml-service/app.py"
click node_hybrid "https://github.com/hemanthvnp/cinescope/blob/main/services/ml-service/recommender/hybrid.py"
click node_collab "https://github.com/hemanthvnp/cinescope/blob/main/services/ml-service/recommender/collaborative.py"
click node_content "https://github.com/hemanthvnp/cinescope/blob/main/services/ml-service/recommender/content_based.py"
click node_explainer "https://github.com/hemanthvnp/cinescope/blob/main/services/ml-service/recommender/explainer.py"
click node_mlstorage "https://github.com/hemanthvnp/cinescope/blob/main/services/ml-service/database.py"
click node_mltmdb "https://github.com/hemanthvnp/cinescope/blob/main/services/ml-service/tmdb_client.py"
click node_clustering "https://github.com/hemanthvnp/cinescope/blob/main/services/ml-service/clustering/api.py"
click node_queryservice "https://github.com/hemanthvnp/cinescope/blob/main/services/ai-orchestration/app.py"
click node_querymodel "https://github.com/hemanthvnp/cinescope/blob/main/services/ai-orchestration/models/query.py"
click node_classifier "https://github.com/hemanthvnp/cinescope/blob/main/services/ai-orchestration/orchestrator/intent_classifier.py"
click node_planner "https://github.com/hemanthvnp/cinescope/blob/main/services/ai-orchestration/orchestrator/tool_planner.py"
click node_engine "https://github.com/hemanthvnp/cinescope/blob/main/services/ai-orchestration/orchestrator/execution_engine.py"
click node_cache "https://github.com/hemanthvnp/cinescope/blob/main/services/ai-orchestration/cache/semantic_cache.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_spa,node_search,node_queryui,node_queryapi,node_searchfilters,node_axios,node_viewer toneBlue
class node_gatewayapp,node_auth,node_userctrl,node_moviectrl,node_ratingctrl,node_watchlist,node_tmdbgateway,node_email toneAmber
class node_genreapi,node_genresvc,node_genredata,node_genredb,node_genretmdb toneMint
class node_mlapi,node_hybrid,node_collab,node_content,node_explainer,node_mlstorage,node_mltmdb,node_clustering toneRose
class node_queryservice,node_querymodel,node_classifier,node_planner,node_engine,node_cache toneIndigo
```

## Components

### Web app

- [React app](https://github.com/hemanthvnp/cinescope/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Search pages](https://github.com/hemanthvnp/cinescope/blob/main/frontend/src/pages/SearchPage.jsx): `frontend/src/pages/SearchPage.jsx`
- [Query Lab](https://github.com/hemanthvnp/cinescope/blob/main/frontend/src/pages/QueryLab.jsx): `frontend/src/pages/QueryLab.jsx`
- [Query API client](https://github.com/hemanthvnp/cinescope/blob/main/frontend/src/api/query.js): `frontend/src/api/query.js`
- [Search filters](https://github.com/hemanthvnp/cinescope/blob/main/frontend/src/context/SearchFilterContext.jsx): `frontend/src/context/SearchFilterContext.jsx`
- [HTTP client](https://github.com/hemanthvnp/cinescope/blob/main/frontend/src/api/axios.js): `frontend/src/api/axios.js`

### API gateway

- [Gateway routes](https://github.com/hemanthvnp/cinescope/blob/main/backend/src/app.js): `backend/src/app.js`
- [Authentication](https://github.com/hemanthvnp/cinescope/blob/main/backend/src/middleware/authMiddleware.js): `backend/src/middleware/authMiddleware.js`
- [User accounts](https://github.com/hemanthvnp/cinescope/blob/main/backend/src/controllers/userController.js): `backend/src/controllers/userController.js`
- [Movie search](https://github.com/hemanthvnp/cinescope/blob/main/backend/src/controllers/movieController.js): `backend/src/controllers/movieController.js`
- [Ratings](https://github.com/hemanthvnp/cinescope/blob/main/backend/src/controllers/ratingController.js): `backend/src/controllers/ratingController.js`
- [Watchlist API](https://github.com/hemanthvnp/cinescope/blob/main/backend/src/routes/watchlistRoutes.js): `backend/src/routes/watchlistRoutes.js`
- [TMDB gateway](https://github.com/hemanthvnp/cinescope/blob/main/backend/src/services/tmdbService.js): `backend/src/services/tmdbService.js`
- [Email OTP](https://github.com/hemanthvnp/cinescope/blob/main/backend/src/services/emailService.js): `backend/src/services/emailService.js`

### Genre fallback

- [Recommendation API](https://github.com/hemanthvnp/cinescope/blob/main/services/recommendation-service/src/controllers/recommendationController.js): `services/recommendation-service/src/controllers/recommendationController.js`
- [Genre recommender](https://github.com/hemanthvnp/cinescope/blob/main/services/recommendation-service/src/services/recommendationService.js): `services/recommendation-service/src/services/recommendationService.js`
- [Preference stores](https://github.com/hemanthvnp/cinescope/blob/main/services/recommendation-service/src/models/UserPreference.js): `services/recommendation-service/src/models/UserPreference.js`
- [Mongo connection](https://github.com/hemanthvnp/cinescope/blob/main/services/recommendation-service/src/config/db.js): `services/recommendation-service/src/config/db.js`
- [TMDB client](https://github.com/hemanthvnp/cinescope/blob/main/services/recommendation-service/src/services/tmdbClient.js): `services/recommendation-service/src/services/tmdbClient.js`

### ML recommendations

- [ML API](https://github.com/hemanthvnp/cinescope/blob/main/services/ml-service/app.py): `services/ml-service/app.py`
- [Hybrid recommender](https://github.com/hemanthvnp/cinescope/blob/main/services/ml-service/recommender/hybrid.py): `services/ml-service/recommender/hybrid.py`
- [Collaborative model](https://github.com/hemanthvnp/cinescope/blob/main/services/ml-service/recommender/collaborative.py): `services/ml-service/recommender/collaborative.py`
- [Content model](https://github.com/hemanthvnp/cinescope/blob/main/services/ml-service/recommender/content_based.py): `services/ml-service/recommender/content_based.py`
- [Recommendation explanations](https://github.com/hemanthvnp/cinescope/blob/main/services/ml-service/recommender/explainer.py): `services/ml-service/recommender/explainer.py`
- [ML data access](https://github.com/hemanthvnp/cinescope/blob/main/services/ml-service/database.py): `services/ml-service/database.py`
- [ML TMDB client](https://github.com/hemanthvnp/cinescope/blob/main/services/ml-service/tmdb_client.py): `services/ml-service/tmdb_client.py`
- [Movie clustering](https://github.com/hemanthvnp/cinescope/blob/main/services/ml-service/clustering/api.py): `services/ml-service/clustering/api.py`

### AI query

- [Query endpoint](https://github.com/hemanthvnp/cinescope/blob/main/services/ai-orchestration/app.py): `services/ai-orchestration/app.py`
- [Query and filters](https://github.com/hemanthvnp/cinescope/blob/main/services/ai-orchestration/models/query.py): `services/ai-orchestration/models/query.py`
- [Intent classifier](https://github.com/hemanthvnp/cinescope/blob/main/services/ai-orchestration/orchestrator/intent_classifier.py): `services/ai-orchestration/orchestrator/intent_classifier.py`
- [Tool planner](https://github.com/hemanthvnp/cinescope/blob/main/services/ai-orchestration/orchestrator/tool_planner.py): `services/ai-orchestration/orchestrator/tool_planner.py`
- [Execution engine](https://github.com/hemanthvnp/cinescope/blob/main/services/ai-orchestration/orchestrator/execution_engine.py): `services/ai-orchestration/orchestrator/execution_engine.py`
- [Tool cache](https://github.com/hemanthvnp/cinescope/blob/main/services/ai-orchestration/cache/semantic_cache.py): `services/ai-orchestration/cache/semantic_cache.py`

### Other components

- **Movie viewer**

## Connections

- Movie viewer → React app: uses (evidence: `README.md`)
- React app → Search pages: routes to (evidence: `frontend/src/App.jsx`)
- React app → Query Lab: routes to (evidence: `frontend/src/App.jsx`)
- Search pages → Search filters: uses filters (evidence: `frontend/src/pages/SearchPage.jsx`)
- Query Lab → Query API client: submits query (evidence: `frontend/src/pages/QueryLab.jsx`)
- Query API client → HTTP client: posts via (evidence: `frontend/src/api/query.js`)
- HTTP client → Gateway routes: calls gateway (evidence: `README.md`)
- Gateway routes → Authentication: protects routes
- Gateway routes → User accounts: routes requests (evidence: `backend/src/app.js`)
- Gateway routes → Movie search: routes requests (evidence: `backend/src/app.js`)
- Gateway routes → Ratings: routes requests (evidence: `backend/src/app.js`)
- Gateway routes → Watchlist API: mounts routes
- Movie search → TMDB gateway: fetches movies (evidence: `backend/src/controllers/movieController.js`)
- User accounts → Email OTP: sends OTP (evidence: `backend/src/controllers/userController.js`)
- User accounts → Recommendation API: syncs preferences (evidence: `backend/src/controllers/userController.js`)
- Gateway routes → ML API: requests recommendations (evidence: `README.md`)
- Gateway routes → Recommendation API: fallback recommendations (evidence: `README.md`)
- Gateway routes → TMDB gateway: fallback trending (evidence: `README.md`)
- Recommendation API → Genre recommender: delegates (evidence: `services/recommendation-service/src/controllers/recommendationController.js`)
- Genre recommender → Preference stores: reads and writes (evidence: `services/recommendation-service/src/services/recommendationService.js`)
- Genre recommender → TMDB client: discovers candidates (evidence: `services/recommendation-service/src/services/recommendationService.js`)
- Mongo connection → Preference stores: connects storage
- ML API → Hybrid recommender: gets recommendations (evidence: `services/ml-service/app.py`)
- Hybrid recommender → Content model: uses content model (evidence: `services/ml-service/recommender/hybrid.py`)
- Hybrid recommender → Collaborative model: uses collaborative model (evidence: `services/ml-service/recommender/hybrid.py`)
- Hybrid recommender → Recommendation explanations: generates explanations (evidence: `services/ml-service/recommender/hybrid.py`)
- Hybrid recommender → ML data access: loads user data (evidence: `services/ml-service/recommender/hybrid.py`)
- Hybrid recommender → ML TMDB client: fetches movie data (evidence: `services/ml-service/recommender/hybrid.py`)
- Movie viewer → Movie clustering: uses analysis
- Query endpoint → Query and filters: validates request (evidence: `services/ai-orchestration/app.py`)
- Query endpoint → Intent classifier: classifies query (evidence: `services/ai-orchestration/app.py`)
- Query endpoint → Tool planner: plans tools (evidence: `README.md`)
- Query endpoint → Execution engine: executes plan (evidence: `README.md`)
- Execution engine → Tool cache: checks and stores (evidence: `services/ai-orchestration/orchestrator/execution_engine.py`)
- Query endpoint → Movie viewer: returns results
