# bucks007/movie_recommendation_system architecture

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

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

## Overview

This Django movie-recommendation product lets visitors browse and search a movie catalog, while signed-in users can manage ratings and watchlists and receive personalized recommendations. The main browse flow serves movie views backed by movie data and recommendation services; the chatbot adds query rewriting, intent routing, recommendations or tools, and an LLM response. The README also documents OMDb enrichment and multiple recommendation modes. Some runtime wiring is unsampled, so uncertain connections are omitted or marked unverified.

Main entry points: [`apps/chatbot/services/chat_pipeline.py`](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/chat_pipeline.py) (Chat Pipeline), [`apps/movies/views.py`](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/movies/views.py) (Movie Views), [`apps/chatbot/services/smart_recommendation_engine.py`](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/smart_recommendation_engine.py) (Smart Ranking), [`apps/recommender/views.py`](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/recommender/views.py) (Recommendation Views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Movie Catalog"]
  node_movies_web["Movie Views<br/>[views.py]"]
  node_movie_data[("Movie Data<br/>[models.py]")]
  node_movie_service["Movie Formatting<br/>[movie_service.py]"]
  node_omdb_enrich["OMDb Enrichment<br/>[enrich_omdb.py]"]
end

subgraph group_recommend["Recommendation Engine"]
  node_recommend_views["Recommendation Views<br/>[views.py]"]
  node_content["Content-Based<br/>[content_based.py]"]
  node_collaborative["Collaborative<br/>[collaborative.py]"]
  node_hybrid["Hybrid<br/>[hybrid.py]"]
  node_personalized["Personalized<br/>[personalized.py]"]
end

subgraph group_chat["Chat Assistant"]
  node_chat_ui["Chat Interface<br/>[chatbot.js]"]
  node_chat_view["Chat Endpoint<br/>[views.py]"]
  node_pipeline["Chat Pipeline<br/>[chat_pipeline.py]"]
  node_rewriter["Query Rewriter<br/>[query_rewriter.py]"]
  node_conversation_rewriter["Conversation Rewriter"]
  node_memory_store[("Session History<br/>[memory_store.py]")]
  node_intent["Intent Detection<br/>[intent_service.py]"]
  node_smart_rec["Smart Ranking"]
  node_semantic["Semantic Search"]
  node_context["Context Builder<br/>[context_builder.py]"]
  node_tool_service["Tool Dispatch<br/>[tool_service.py]"]
  node_search_tools["Movie Search Tool<br/>[search_tools.py]"]
  node_serializer["Movie Serializer"]
  node_llm["LLM Service<br/>[llm_service.py]"]
  node_prompt["Prompt Template<br/>[prompt_template.py]"]
  node_chat_memory[("Chat Memory<br/>[memory_service.py]")]
end

subgraph group_accounts["Accounts &amp; Activity"]
  node_user_views["User Views<br/>[views.py]"]
  node_user_data[("User &amp; Activity Data<br/>[models.py]")]
end

node_visitor(("Visitor"))
node_omdb["OMDb API"]
node_chat_user(("Chat User"))
node_gemini["Google Gemini"]

node_visitor -->|"browses"| node_movies_web
node_movies_web -->|"queries"| node_movie_data
node_movies_web -->|"requests similar"| node_hybrid
node_movies_web -->|"requests personalized"| node_personalized
node_movie_data -->|"enriched from"| node_omdb_enrich
node_omdb_enrich -->|"fetches metadata"| node_omdb
node_movies_web -.->|"formats titles"| node_movie_service
node_recommend_views -.->|"offers"| node_content
node_recommend_views -.->|"offers"| node_collaborative
node_recommend_views -.->|"offers"| node_hybrid
node_recommend_views -.->|"offers"| node_personalized
node_chat_user -->|"asks"| node_chat_ui
node_chat_ui -.->|"submits message"| node_chat_view
node_chat_view -.->|"invokes"| node_pipeline
node_pipeline -->|"rewrites query"| node_rewriter
node_rewriter -->|"rewrites from memory"| node_conversation_rewriter
node_rewriter -->|"reads history"| node_memory_store
node_pipeline -->|"detects intent"| node_intent
node_pipeline -->|"gets recommendations"| node_smart_rec
node_smart_rec -->|"searches semantically"| node_semantic
node_smart_rec -->|"combines results"| node_content
node_smart_rec -->|"combines results"| node_personalized
node_smart_rec -->|"ranks movies"| node_movie_data
node_pipeline -->|"builds context"| node_context
node_pipeline -->|"dispatches tools"| node_tool_service
node_tool_service -.->|"dispatches"| node_search_tools
node_search_tools -->|"searches titles"| node_movie_data
node_pipeline -->|"generates answer"| node_llm
node_llm -->|"uses prompt"| node_prompt
node_llm -->|"loads and saves"| node_chat_memory
node_llm -->|"calls model"| node_gemini
node_pipeline -->|"serializes movies"| node_serializer
node_user_views -->|"gets recommendations"| node_personalized
node_user_views -.->|"reads activity"| node_user_data

click node_movies_web "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/movies/views.py"
click node_movie_data "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/movies/models.py"
click node_movie_service "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/movies/services/movie_service.py"
click node_omdb_enrich "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/movies/management/commands/enrich_omdb.py"
click node_recommend_views "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/recommender/views.py"
click node_content "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/recommender/services/content_based.py"
click node_collaborative "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/recommender/services/collaborative.py"
click node_hybrid "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/recommender/services/hybrid.py"
click node_personalized "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/recommender/services/personalized.py"
click node_chat_ui "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/static/chatbot/chatbot.js"
click node_chat_view "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/views.py"
click node_pipeline "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/chat_pipeline.py"
click node_rewriter "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/query_rewriter.py"
click node_conversation_rewriter "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/conversation_rewriter.py"
click node_memory_store "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/memory_store.py"
click node_intent "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/intent_service.py"
click node_smart_rec "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/smart_recommendation_engine.py"
click node_semantic "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/semantic_search_service.py"
click node_context "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/context_builder.py"
click node_tool_service "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/tool_service.py"
click node_search_tools "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/tools/search_tools.py"
click node_serializer "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/movie_serializer.py"
click node_llm "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/llm_service.py"
click node_prompt "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/prompt_template.py"
click node_chat_memory "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/memory_service.py"
click node_user_views "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/users/views.py"
click node_user_data "https://github.com/bucks007/movie_recommendation_system/blob/main/apps/users/models.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_movies_web,node_movie_data,node_movie_service,node_omdb_enrich,node_chat_user toneBlue
class node_recommend_views,node_content,node_collaborative,node_hybrid,node_personalized toneAmber
class node_chat_ui,node_chat_view,node_pipeline,node_rewriter,node_conversation_rewriter,node_memory_store,node_intent,node_smart_rec,node_semantic,node_context,node_tool_service,node_search_tools,node_serializer,node_llm,node_prompt,node_chat_memory,node_omdb toneMint
class node_user_views,node_user_data toneRose
class node_visitor,node_gemini toneIndigo
```

## Components

### Movie Catalog

- [Movie Views](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/movies/views.py): `apps/movies/views.py`
- [Movie Data](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/movies/models.py): `apps/movies/models.py`
- [Movie Formatting](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/movies/services/movie_service.py): `apps/movies/services/movie_service.py`
- [OMDb Enrichment](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/movies/management/commands/enrich_omdb.py): `apps/movies/management/commands/enrich_omdb.py`

### Recommendation Engine

- [Recommendation Views](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/recommender/views.py): `apps/recommender/views.py`
- [Content-Based](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/recommender/services/content_based.py): `apps/recommender/services/content_based.py`
- [Collaborative](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/recommender/services/collaborative.py): `apps/recommender/services/collaborative.py`
- [Hybrid](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/recommender/services/hybrid.py): `apps/recommender/services/hybrid.py`
- [Personalized](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/recommender/services/personalized.py): `apps/recommender/services/personalized.py`

### Chat Assistant

- [Chat Interface](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/static/chatbot/chatbot.js): `apps/chatbot/static/chatbot/chatbot.js`
- [Chat Endpoint](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/views.py): `apps/chatbot/views.py`
- [Chat Pipeline](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/chat_pipeline.py): `apps/chatbot/services/chat_pipeline.py`
- [Query Rewriter](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/query_rewriter.py): `apps/chatbot/services/query_rewriter.py`
- [Conversation Rewriter](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/conversation_rewriter.py): `apps/chatbot/services/conversation_rewriter.py`
- [Session History](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/memory_store.py): `apps/chatbot/services/memory_store.py`
- [Intent Detection](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/intent_service.py): `apps/chatbot/services/intent_service.py`
- [Smart Ranking](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/smart_recommendation_engine.py): `apps/chatbot/services/smart_recommendation_engine.py`
- [Semantic Search](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/semantic_search_service.py): `apps/chatbot/services/semantic_search_service.py`
- [Context Builder](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/context_builder.py): `apps/chatbot/services/context_builder.py`
- [Tool Dispatch](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/tool_service.py): `apps/chatbot/services/tool_service.py`
- [Movie Search Tool](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/tools/search_tools.py): `apps/chatbot/services/tools/search_tools.py`
- [Movie Serializer](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/movie_serializer.py): `apps/chatbot/services/movie_serializer.py`
- [LLM Service](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/llm_service.py): `apps/chatbot/services/llm_service.py`
- [Prompt Template](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/prompt_template.py): `apps/chatbot/services/prompt_template.py`
- [Chat Memory](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/chatbot/services/memory_service.py): `apps/chatbot/services/memory_service.py`

### Accounts & Activity

- [User Views](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/users/views.py): `apps/users/views.py`
- [User & Activity Data](https://github.com/bucks007/movie_recommendation_system/blob/main/apps/users/models.py): `apps/users/models.py`

### Other components

- **Visitor**
- **OMDb API**
- **Chat User**
- **Google Gemini**

## Connections

- Visitor → Movie Views: browses
- Movie Views → Movie Data: queries (evidence: `apps/movies/views.py`)
- Movie Views → Hybrid: requests similar (evidence: `apps/movies/views.py`)
- Movie Views → Personalized: requests personalized (evidence: `apps/movies/views.py`)
- Movie Data → OMDb Enrichment: enriched from (evidence: `apps/movies/management/commands/enrich_omdb.py`)
- OMDb Enrichment → OMDb API: fetches metadata
- Movie Views → Movie Formatting: formats titles
- Recommendation Views → Content-Based: offers
- Recommendation Views → Collaborative: offers
- Recommendation Views → Hybrid: offers
- Recommendation Views → Personalized: offers
- Chat User → Chat Interface: asks
- Chat Interface → Chat Endpoint: submits message
- Chat Endpoint → Chat Pipeline: invokes
- Chat Pipeline → Query Rewriter: rewrites query (evidence: `apps/chatbot/services/chat_pipeline.py`)
- Query Rewriter → Conversation Rewriter: rewrites from memory (evidence: `apps/chatbot/services/query_rewriter.py`)
- Query Rewriter → Session History: reads history (evidence: `apps/chatbot/services/query_rewriter.py`)
- Chat Pipeline → Intent Detection: detects intent (evidence: `apps/chatbot/services/chat_pipeline.py`)
- Chat Pipeline → Smart Ranking: gets recommendations (evidence: `apps/chatbot/services/chat_pipeline.py`)
- Smart Ranking → Semantic Search: searches semantically (evidence: `apps/chatbot/services/smart_recommendation_engine.py`)
- Smart Ranking → Content-Based: combines results (evidence: `apps/chatbot/services/smart_recommendation_engine.py`)
- Smart Ranking → Personalized: combines results (evidence: `apps/chatbot/services/smart_recommendation_engine.py`)
- Smart Ranking → Movie Data: ranks movies (evidence: `apps/chatbot/services/smart_recommendation_engine.py`)
- Chat Pipeline → Context Builder: builds context (evidence: `apps/chatbot/services/chat_pipeline.py`)
- Chat Pipeline → Tool Dispatch: dispatches tools (evidence: `apps/chatbot/services/chat_pipeline.py`)
- Tool Dispatch → Movie Search Tool: dispatches
- Movie Search Tool → Movie Data: searches titles (evidence: `apps/chatbot/services/tools/search_tools.py`)
- Chat Pipeline → LLM Service: generates answer (evidence: `apps/chatbot/services/chat_pipeline.py`)
- LLM Service → Prompt Template: uses prompt (evidence: `apps/chatbot/services/llm_service.py`)
- LLM Service → Chat Memory: loads and saves (evidence: `apps/chatbot/services/llm_service.py`)
- LLM Service → Google Gemini: calls model (evidence: `apps/chatbot/services/llm_service.py`)
- Chat Pipeline → Movie Serializer: serializes movies (evidence: `apps/chatbot/services/chat_pipeline.py`)
- User Views → Personalized: gets recommendations (evidence: `apps/users/views.py`)
- User Views → User & Activity Data: reads activity