# jonbuwembo/movie-recommender-app architecture

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

- Interactive diagram: https://gitdiagram.com/jonbuwembo/movie-recommender-app
- Repository: https://github.com/jonbuwembo/movie-recommender-app

## Overview

Midnight Scoop is a full-stack movie discovery and recommendation platform. Users authenticate, browse or search films, view details, rate movies, manage a watchlist, and ask a movie chatbot; the Flask API serves these actions and recommendation results. Recommendations combine popularity for new users, content similarity for lightly rated users, and collaborative filtering for more active users. The README documents the main product capabilities and React-to-API architecture; sampled backend excerpts show service and persistence behavior, but not every route implementation.

Main entry points: [`backend/app.py`](https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/app.py) (Flask application), [`backend/services/recommendation_service.py`](https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/services/recommendation_service.py) (Recommendation service), [`frontend/src/App.tsx`](https://github.com/jonbuwembo/movie-recommender-app/blob/main/frontend/src/App.tsx) (React application), [`backend/services/search_service.py`](https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/services/search_service.py) (Search service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_webapp["React application<br/>[App.tsx]"]
  node_authui["Auth context<br/>[AuthContext.tsx]"]
  node_navigation["Navigation and search<br/>[Navbar.js]"]
  node_discovery["Movie discovery<br/>[MoviesDisplay.js]"]
  node_home["Home recommendations<br/>[LandingPage.js]"]
  node_details["Movie details and ratings<br/>[MovieDetails.js]"]
  node_watchlistui["Watchlist actions<br/>[useWatchlist.tsx]"]
  node_chatui["Chat screen<br/>[ChatStartScreen.js]"]
end

subgraph group_api["API and services"]
  node_flask["Flask application<br/>[app.py]"]
  node_authroutes["Authentication routes<br/>[auth.py]"]
  node_movieroutes["Movie routes<br/>[movies.py]"]
  node_searchroutes["Search routes<br/>[search.py]"]
  node_chatroutes["Chat routes<br/>[chatbot.py]"]
  node_moviesvc["Movie services<br/>[movie_service.py]"]
  node_searchsvc["Search service<br/>[search_service.py]"]
  node_chatsvc["Chatbot service<br/>[chatbot_service.py]"]
end

subgraph group_recommendations["Recommendation engine"]
  node_recsvc["Recommendation service"]
  node_contentmodel["Content similarity<br/>[content_based.py]"]
  node_collabmodel["Collaborative model<br/>[svd_recommender.py]"]
end

subgraph group_persistence["Persistence and identity"]
  node_identity["JWT identity<br/>[auth_utils.py]"]
  node_models["Movie and user records<br/>[movie_model.py]"]
  node_database[("PostgreSQL<br/>[db_connection.py]")]
end

node_viewer(("Movie viewer"))

node_viewer -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_discovery
node_webapp -->|"routes to"| node_home
node_webapp -->|"routes to"| node_details
node_webapp -->|"routes to"| node_chatui
node_navigation -->|"navigates to"| node_discovery
node_authui -->|"sends REST requests"| node_flask
node_discovery -->|"requests movie data"| node_flask
node_home -->|"requests recommendations"| node_flask
node_details -->|"requests details and ratings"| node_flask
node_watchlistui -->|"calls watchlist API"| node_flask
node_chatui -->|"uses REST API"| node_flask
node_flask -->|"registers"| node_authroutes
node_flask -->|"registers"| node_movieroutes
node_flask -->|"registers"| node_searchroutes
node_flask -->|"registers"| node_chatroutes
node_authroutes -->|"uses"| node_identity
node_authroutes -->|"uses"| node_models
node_movieroutes -->|"dispatches to"| node_moviesvc
node_movieroutes -->|"dispatches to"| node_recsvc
node_searchroutes -->|"dispatches to"| node_searchsvc
node_chatroutes -->|"dispatches to"| node_chatsvc
node_searchsvc -->|"gets similar films"| node_contentmodel
node_searchsvc -->|"looks up films"| node_recsvc
node_moviesvc -->|"uses records"| node_models
node_moviesvc -->|"gets current user"| node_identity
node_recsvc -->|"gets similar films"| node_contentmodel
node_recsvc -->|"loads recommender"| node_collabmodel
node_recsvc -->|"reads ratings and history"| node_models
node_recsvc -->|"queries movie data"| node_database
node_searchsvc -->|"queries catalog"| node_database
node_models -.->|"persists records"| node_database

click node_webapp "https://github.com/jonbuwembo/movie-recommender-app/blob/main/frontend/src/App.tsx"
click node_authui "https://github.com/jonbuwembo/movie-recommender-app/blob/main/frontend/src/AuthContext.tsx"
click node_navigation "https://github.com/jonbuwembo/movie-recommender-app/blob/main/frontend/src/components/Navbar/Navbar.js"
click node_discovery "https://github.com/jonbuwembo/movie-recommender-app/blob/main/frontend/src/pages/MoviesDisplay.js"
click node_home "https://github.com/jonbuwembo/movie-recommender-app/blob/main/frontend/src/pages/LandingPage.js"
click node_details "https://github.com/jonbuwembo/movie-recommender-app/blob/main/frontend/src/pages/MovieDetails.js"
click node_watchlistui "https://github.com/jonbuwembo/movie-recommender-app/blob/main/frontend/src/useWatchlist.tsx"
click node_chatui "https://github.com/jonbuwembo/movie-recommender-app/blob/main/frontend/src/pages/ChatStartScreen.js"
click node_flask "https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/app.py"
click node_authroutes "https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/routes/auth.py"
click node_movieroutes "https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/routes/movies.py"
click node_searchroutes "https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/routes/search.py"
click node_chatroutes "https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/routes/chatbot.py"
click node_moviesvc "https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/services/movie_service.py"
click node_searchsvc "https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/services/search_service.py"
click node_chatsvc "https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/services/chatbot_service.py"
click node_recsvc "https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/services/recommendation_service.py"
click node_contentmodel "https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/models/content_based.py"
click node_collabmodel "https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/recommender/svd_recommender.py"
click node_identity "https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/utils/auth_utils.py"
click node_models "https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/models/movie_model.py"
click node_database "https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/database/db_connection.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_webapp,node_authui,node_navigation,node_discovery,node_home,node_details,node_watchlistui,node_chatui,node_viewer toneBlue
class node_flask,node_authroutes,node_movieroutes,node_searchroutes,node_chatroutes,node_moviesvc,node_searchsvc,node_chatsvc toneAmber
class node_recsvc,node_contentmodel,node_collabmodel toneMint
class node_identity,node_models,node_database toneRose
```

## Components

### Web experience

- [React application](https://github.com/jonbuwembo/movie-recommender-app/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Auth context](https://github.com/jonbuwembo/movie-recommender-app/blob/main/frontend/src/AuthContext.tsx): `frontend/src/AuthContext.tsx`
- [Navigation and search](https://github.com/jonbuwembo/movie-recommender-app/blob/main/frontend/src/components/Navbar/Navbar.js): `frontend/src/components/Navbar/Navbar.js`
- [Movie discovery](https://github.com/jonbuwembo/movie-recommender-app/blob/main/frontend/src/pages/MoviesDisplay.js): `frontend/src/pages/MoviesDisplay.js`
- [Home recommendations](https://github.com/jonbuwembo/movie-recommender-app/blob/main/frontend/src/pages/LandingPage.js): `frontend/src/pages/LandingPage.js`
- [Movie details and ratings](https://github.com/jonbuwembo/movie-recommender-app/blob/main/frontend/src/pages/MovieDetails.js): `frontend/src/pages/MovieDetails.js`
- [Watchlist actions](https://github.com/jonbuwembo/movie-recommender-app/blob/main/frontend/src/useWatchlist.tsx): `frontend/src/useWatchlist.tsx`
- [Chat screen](https://github.com/jonbuwembo/movie-recommender-app/blob/main/frontend/src/pages/ChatStartScreen.js): `frontend/src/pages/ChatStartScreen.js`

### API and services

- [Flask application](https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/app.py): `backend/app.py`
- [Authentication routes](https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/routes/auth.py): `backend/routes/auth.py`
- [Movie routes](https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/routes/movies.py): `backend/routes/movies.py`
- [Search routes](https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/routes/search.py): `backend/routes/search.py`
- [Chat routes](https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/routes/chatbot.py): `backend/routes/chatbot.py`
- [Movie services](https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/services/movie_service.py): `backend/services/movie_service.py`
- [Search service](https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/services/search_service.py): `backend/services/search_service.py`
- [Chatbot service](https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/services/chatbot_service.py): `backend/services/chatbot_service.py`

### Recommendation engine

- [Recommendation service](https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/services/recommendation_service.py): `backend/services/recommendation_service.py`
- [Content similarity](https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/models/content_based.py): `backend/models/content_based.py`
- [Collaborative model](https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/recommender/svd_recommender.py): `backend/recommender/svd_recommender.py`

### Persistence and identity

- [JWT identity](https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/utils/auth_utils.py): `backend/utils/auth_utils.py`
- [Movie and user records](https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/models/movie_model.py): `backend/models/movie_model.py`
- [PostgreSQL](https://github.com/jonbuwembo/movie-recommender-app/blob/main/backend/database/db_connection.py): `backend/database/db_connection.py`

### Other components

- **Movie viewer**

## Connections

- Movie viewer → React application: uses (evidence: `README.md`)
- React application → Movie discovery: routes to (evidence: `frontend/src/App.tsx`)
- React application → Home recommendations: routes to (evidence: `frontend/src/App.tsx`)
- React application → Movie details and ratings: routes to (evidence: `frontend/src/App.tsx`)
- React application → Chat screen: routes to (evidence: `frontend/src/App.tsx`)
- Navigation and search → Movie discovery: navigates to (evidence: `frontend/src/components/Navbar/Navbar.js`)
- Auth context → Flask application: sends REST requests (evidence: `README.md`)
- Movie discovery → Flask application: requests movie data (evidence: `README.md`)
- Home recommendations → Flask application: requests recommendations (evidence: `README.md`)
- Movie details and ratings → Flask application: requests details and ratings (evidence: `README.md`)
- Watchlist actions → Flask application: calls watchlist API (evidence: `frontend/src/useWatchlist.tsx`)
- Chat screen → Flask application: uses REST API (evidence: `README.md`)
- Flask application → Authentication routes: registers (evidence: `backend/app.py`)
- Flask application → Movie routes: registers (evidence: `backend/app.py`)
- Flask application → Search routes: registers (evidence: `backend/app.py`)
- Flask application → Chat routes: registers (evidence: `backend/app.py`)
- Authentication routes → JWT identity: uses (evidence: `backend/routes/auth.py`)
- Authentication routes → Movie and user records: uses (evidence: `backend/routes/auth.py`)
- Movie routes → Movie services: dispatches to (evidence: `backend/routes/movies.py`)
- Movie routes → Recommendation service: dispatches to (evidence: `backend/routes/movies.py`)
- Search routes → Search service: dispatches to (evidence: `backend/routes/search.py`)
- Chat routes → Chatbot service: dispatches to (evidence: `backend/routes/chatbot.py`)
- Search service → Content similarity: gets similar films (evidence: `backend/services/search_service.py`)
- Search service → Recommendation service: looks up films (evidence: `backend/services/search_service.py`)
- Movie services → Movie and user records: uses records (evidence: `backend/services/movie_service.py`)
- Movie services → JWT identity: gets current user (evidence: `backend/services/movie_service.py`)
- Recommendation service → Content similarity: gets similar films (evidence: `backend/services/recommendation_service.py`)
- Recommendation service → Collaborative model: loads recommender (evidence: `backend/services/recommendation_service.py`)
- Recommendation service → Movie and user records: reads ratings and history (evidence: `backend/services/recommendation_service.py`)
- Recommendation service → PostgreSQL: queries movie data (evidence: `backend/services/recommendation_service.py`)
- Search service → PostgreSQL: queries catalog (evidence: `backend/services/search_service.py`)
- Movie and user records → PostgreSQL: persists records
