# raghavs16/movie_recommendation_system architecture

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

- Interactive diagram: https://gitdiagram.com/raghavs16/movie_recommendation_system
- Repository: https://github.com/raghavs16/movie_recommendation_system

## Overview

#### Purpose and Runtime Topology
FilmoBot is a React single-page movie chatbot backed by a Flask API. It converts conversational movie requests into structured search intents, retrieves and enriches movie data, and supports authenticated persistence for chats, profiles, and watchlists. The browser runs from `client/src/index.js`; Flask is started through `server/app.py`.

#### Frontend Application Shell
`client/src/App.jsx` owns React Router routing and application-level state across the chat and account-oriented screens. The primary user journey begins in `client/src/ChatPage.jsx`; onboarding and authentication are handled by `client/src/Splash.jsx`, `client/src/Welcome.jsx`, `client/src/Login.jsx`, and `client/src/Signup.jsx`. API targeting is centralized in `client/src/config.js`.

#### Chat and Recommendation Presentation
`client/src/ChatPage.jsx` sends user prompts to the backend, renders conversational results, and participates in chat-history behavior. `client/src/MovieCard.jsx` is the reusable movie-result boundary: it presents returned metadata and exposes trailer and watchlist actions. `client/src/Sidebar.jsx` provides navigation and access to persisted chat sessions.

#### User State and Persistence UX
The client stores JWT authentication and configurable preferences locally; settings include language, result count, notification choices, and chat-history behavior. `client/src/SettingsPage.jsx` owns this preference surface, while `client/src/WatchlistPage.jsx` and `client/src/ProfilePage.jsx` consume backend-backed user data. The backend SQLite database is represented by `server/filmobot.db`; API and database routes/models reside in `server/app.py`.

#### Backend API and Account Boundary
`server/app.py` is the Flask composition point: it exposes the API, performs JWT-based authentication, handles account/profile/watchlist/history operations, manages password-reset OTP email flow, and accepts profile image uploads. Uploaded images cross into server-local storage at `server/static/uploads/`. Authentication uses Flask-JWT-Extended, passwords use Flask-Bcrypt, and reset email uses Flask-Mail with Gmail SMTP.

#### AI Intent-to-Search Pipeline
Movie-query handling enters `server/app.py` and delegates intent extraction to `server/ai_processor.py`. That module calls Groq’s LLaMA 3.1 8B API for structured intent and supplies a rule-based fallback when the LLM is unavailable. The resulting intent selects discover, direct search, similar-movie, person-filmography, or song-to-movie paths; fuzzy and phonetic recovery for misspelled titles/names is implemented in `server/movie_search.py`.

#### External Movie Data Integration
`server/tmdb_client.py` is the main TMDB boundary for discovery, search, recommendations, language/genre/mood mapping, trailers, and streaming-oriented metadata. `server/tmdb_retry.py` wraps TMDB access with retry behavior. Backend responses are enriched with OMDb data such as IMDb ratings and cast, then ranked before returning to the client. Required external services are Groq, TMDB, OMDb, Gmail SMTP, and client-side EmailJS for `client/src/ContactPage.jsx`.

Main entry points: [`server/app.py`](https://github.com/raghavs16/movie_recommendation_system/blob/main/server/app.py) (Flask API), [`client/src/App.jsx`](https://github.com/raghavs16/movie_recommendation_system/blob/main/client/src/App.jsx) (App shell & routes), [`server/ai_processor.py`](https://github.com/raghavs16/movie_recommendation_system/blob/main/server/ai_processor.py) (Intent extraction), [`server/tmdb_client.py`](https://github.com/raghavs16/movie_recommendation_system/blob/main/server/tmdb_client.py) (TMDB integration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React client"]
  node_client_entry["Browser entry<br/>React bootstrap<br/>[index.js]"]
  node_app_shell["App shell &amp; routes<br/>React router<br/>[App.jsx]"]
  node_chat_page["Chat experience<br/>React page<br/>[ChatPage.jsx]"]
  node_movie_card["Movie results<br/>React component<br/>[MovieCard.jsx]"]
  node_sidebar["Chat navigation<br/>React component<br/>[Sidebar.jsx]"]
  node_account_screens["Account &amp; onboarding<br/>React screens<br/>[Login.jsx]"]
  node_user_pages["Profile, settings &amp; watchlist<br/>React pages<br/>[SettingsPage.jsx]"]
  node_api_config["API configuration<br/>client config<br/>[config.js]"]
  node_contact_page["Contact form<br/>React page<br/>[ContactPage.jsx]"]
end

subgraph group_backend["Flask backend"]
  node_flask_api{{"Flask API<br/>API composition<br/>[app.py]"}}
  node_intent_processor["Intent extraction<br/>AI pipeline<br/>[ai_processor.py]"]
  node_movie_search["Query recovery<br/>search logic<br/>[movie_search.py]"]
  node_tmdb_client["TMDB integration<br/>movie data client<br/>[tmdb_client.py]"]
  node_tmdb_retry["TMDB retry wrapper<br/>resilience layer<br/>[tmdb_retry.py]"]
  node_app_database[("Application database<br/>SQLite<br/>[filmobot.db]")]
  node_uploads[("Profile uploads<br/>local storage")]
end

subgraph group_external["External services"]
  node_groq{{"Groq LLaMA API<br/>LLM service"}}
  node_tmdb{{"TMDB API<br/>movie data service"}}
  node_omdb{{"OMDb API<br/>metadata service"}}
  node_gmail{{"Gmail SMTP<br/>email service"}}
  node_emailjs{{"EmailJS<br/>client email service"}}
end

node_client_entry -->|"mounts"| node_app_shell
node_app_shell -->|"routes to"| node_chat_page
node_app_shell -->|"routes to"| node_account_screens
node_app_shell -->|"routes to"| node_user_pages
node_chat_page -->|"renders"| node_movie_card
node_sidebar -->|"loads chat history"| node_flask_api
node_chat_page -->|"submits prompts"| node_flask_api
node_movie_card -->|"watchlist actions"| node_flask_api
node_account_screens -->|"auth requests"| node_flask_api
node_user_pages -->|"user data &amp; preferences"| node_flask_api
node_api_config -.->|"API target"| node_flask_api
node_contact_page -->|"sends contact email"| node_emailjs
node_flask_api -->|"movie query intent"| node_intent_processor
node_intent_processor -->|"structured intent"| node_groq
node_intent_processor -->|"recovery path"| node_movie_search
node_intent_processor -->|"selects search path"| node_tmdb_client
node_movie_search -->|"resolved query"| node_tmdb_client
node_tmdb_client -->|"uses"| node_tmdb_retry
node_tmdb_retry -->|"retried requests"| node_tmdb
node_tmdb_client -->|"enriches results"| node_omdb
node_flask_api -->|"persists user data"| node_app_database
node_flask_api -->|"stores images"| node_uploads
node_flask_api -->|"sends reset OTP"| node_gmail

click node_client_entry "https://github.com/raghavs16/movie_recommendation_system/blob/main/client/src/index.js"
click node_app_shell "https://github.com/raghavs16/movie_recommendation_system/blob/main/client/src/App.jsx"
click node_chat_page "https://github.com/raghavs16/movie_recommendation_system/blob/main/client/src/ChatPage.jsx"
click node_movie_card "https://github.com/raghavs16/movie_recommendation_system/blob/main/client/src/MovieCard.jsx"
click node_sidebar "https://github.com/raghavs16/movie_recommendation_system/blob/main/client/src/Sidebar.jsx"
click node_account_screens "https://github.com/raghavs16/movie_recommendation_system/blob/main/client/src/Login.jsx"
click node_user_pages "https://github.com/raghavs16/movie_recommendation_system/blob/main/client/src/SettingsPage.jsx"
click node_api_config "https://github.com/raghavs16/movie_recommendation_system/blob/main/client/src/config.js"
click node_contact_page "https://github.com/raghavs16/movie_recommendation_system/blob/main/client/src/ContactPage.jsx"
click node_flask_api "https://github.com/raghavs16/movie_recommendation_system/blob/main/server/app.py"
click node_intent_processor "https://github.com/raghavs16/movie_recommendation_system/blob/main/server/ai_processor.py"
click node_movie_search "https://github.com/raghavs16/movie_recommendation_system/blob/main/server/movie_search.py"
click node_tmdb_client "https://github.com/raghavs16/movie_recommendation_system/blob/main/server/tmdb_client.py"
click node_tmdb_retry "https://github.com/raghavs16/movie_recommendation_system/blob/main/server/tmdb_retry.py"
click node_app_database "https://github.com/raghavs16/movie_recommendation_system/blob/main/server/filmobot.db"

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_client_entry,node_app_shell,node_chat_page,node_movie_card,node_sidebar,node_account_screens,node_user_pages,node_api_config,node_contact_page toneBlue
class node_flask_api,node_intent_processor,node_movie_search,node_tmdb_client,node_tmdb_retry,node_app_database,node_uploads toneAmber
class node_groq,node_tmdb,node_omdb,node_gmail,node_emailjs toneMint
```

## Components

### React client

- [Browser entry](https://github.com/raghavs16/movie_recommendation_system/blob/main/client/src/index.js): React bootstrap · `client/src/index.js`
- [App shell & routes](https://github.com/raghavs16/movie_recommendation_system/blob/main/client/src/App.jsx): React router · Owns application-level state and screen routing. · `client/src/App.jsx`
- [Chat experience](https://github.com/raghavs16/movie_recommendation_system/blob/main/client/src/ChatPage.jsx): React page · Sends prompts and renders conversational results. · `client/src/ChatPage.jsx`
- [Movie results](https://github.com/raghavs16/movie_recommendation_system/blob/main/client/src/MovieCard.jsx): React component · Provides trailer and watchlist actions. · `client/src/MovieCard.jsx`
- [Chat navigation](https://github.com/raghavs16/movie_recommendation_system/blob/main/client/src/Sidebar.jsx): React component · Provides access to persisted chat sessions. · `client/src/Sidebar.jsx`
- [Account & onboarding](https://github.com/raghavs16/movie_recommendation_system/blob/main/client/src/Login.jsx): React screens · Splash, welcome, login, and signup flows. · `client/src/Login.jsx`
- [Profile, settings & watchlist](https://github.com/raghavs16/movie_recommendation_system/blob/main/client/src/SettingsPage.jsx): React pages · Manages preferences and displays user-backed data. · `client/src/SettingsPage.jsx`
- [API configuration](https://github.com/raghavs16/movie_recommendation_system/blob/main/client/src/config.js): client config · `client/src/config.js`
- [Contact form](https://github.com/raghavs16/movie_recommendation_system/blob/main/client/src/ContactPage.jsx): React page · `client/src/ContactPage.jsx`

### Flask backend

- [Flask API](https://github.com/raghavs16/movie_recommendation_system/blob/main/server/app.py): API composition · Handles JWT accounts, profiles, watchlists, history, OTP reset, and uploads. · `server/app.py`
- [Intent extraction](https://github.com/raghavs16/movie_recommendation_system/blob/main/server/ai_processor.py): AI pipeline · Uses LLM intent parsing with a rule-based fallback. · `server/ai_processor.py`
- [Query recovery](https://github.com/raghavs16/movie_recommendation_system/blob/main/server/movie_search.py): search logic · Recovers misspelled movie titles and names. · `server/movie_search.py`
- [TMDB integration](https://github.com/raghavs16/movie_recommendation_system/blob/main/server/tmdb_client.py): movie data client · Handles discovery, search, recommendations, trailers, and metadata. · `server/tmdb_client.py`
- [TMDB retry wrapper](https://github.com/raghavs16/movie_recommendation_system/blob/main/server/tmdb_retry.py): resilience layer · `server/tmdb_retry.py`
- [Application database](https://github.com/raghavs16/movie_recommendation_system/blob/main/server/filmobot.db): SQLite · Stores account, chat, profile, and watchlist data. · `server/filmobot.db`
- **Profile uploads**: local storage

### External services

- **Groq LLaMA API**: LLM service
- **TMDB API**: movie data service
- **OMDb API**: metadata service · Supplies IMDb ratings and cast enrichment.
- **Gmail SMTP**: email service · Delivers password-reset OTP email.
- **EmailJS**: client email service

## Connections

- Browser entry → App shell & routes: mounts
- App shell & routes → Chat experience: routes to
- App shell & routes → Account & onboarding: routes to
- App shell & routes → Profile, settings & watchlist: routes to
- Chat experience → Movie results: renders
- Chat navigation → Flask API: loads chat history
- Chat experience → Flask API: submits prompts
- Movie results → Flask API: watchlist actions
- Account & onboarding → Flask API: auth requests
- Profile, settings & watchlist → Flask API: user data & preferences
- API configuration → Flask API: API target
- Contact form → EmailJS: sends contact email
- Flask API → Intent extraction: movie query intent
- Intent extraction → Groq LLaMA API: structured intent
- Intent extraction → Query recovery: recovery path
- Intent extraction → TMDB integration: selects search path
- Query recovery → TMDB integration: resolved query
- TMDB integration → TMDB retry wrapper: uses
- TMDB retry wrapper → TMDB API: retried requests
- TMDB integration → OMDb API: enriches results
- Flask API → Application database: persists user data
- Flask API → Profile uploads: stores images
- Flask API → Gmail SMTP: sends reset OTP