🍿 CineGraph

A Next-Generation Movie Discovery & Recommendation Platform

CineGraph is a comprehensive, full-stack movie discovery platform. It provides users with an immersive experience for exploring films, cast, and crew, while offering highly personalized movie recommendations powered by a hybrid architecture of traditional relational data, Graph Machine Learning, and an advanced GraphRAG (Graph Retrieval-Augmented Generation) AI.

---

🏗️ Architecture

The project is split into three core microservices communicating securely over REST and gRPC:

1. Frontend Client (/Client/Movie reviews): A modern, responsive React application built with Vite, Redux Toolkit, and Tailwind CSS.
2. Primary API Server (/server/movie_server): A high-performance Go backend that manages core business logic, user authentication, AI routing via Gemini/LangChainGo, and MongoDB queries.
3. Recommendation Engine (/server/recommendation_server): A specialized Python gRPC microservice leveraging Neo4j Graph Data Science (GDS) and Natural Language Processing (NLP) to generate intelligent, context-aware movie recommendations.

---

✨ Detailed Features

🧠 CineGraph AI Search (GraphRAG)

• Natural Language Discovery: Tell the AI exactly what you're in the mood for (e.g., "dark and gritty sci-fi about time travel").
• Intelligent Routing: The Go server uses Gemini to intelligently route your query. Structured queries generate raw Cypher to query Neo4j directly, while vibe-based queries use semantic theme extraction.
• Dynamic AI Prompts: Complex AI routing logic is securely abstracted into a prompts.json config file that can be hot-reloaded without restarting the server.
• Conversational Summaries: The AI reads the graph results and streams a conversational, personalized explanation directly to you of why these movies match your exact mood.

📊 Graph Machine Learning Recommendations

The Python recommendation server uses Neo4j Graph Data Science to provide hyper-personalized recommendations across multiple dimensions:

• Because of your Taste (FastRP): Utilizes Fast Random Projection (FastRP) to create node embeddings based on your watch history, surfacing movies with identical underlying structural patterns.
• From your Communities (Louvain): Employs the Louvain Community Detection algorithm to map you to a graph cluster of like-minded users, recommending movies your specific "community" is watching.
• Hidden Gems (PPR): Uses Personalized PageRank to find highly influential but lesser-known movies connected to your favorite directors and genres.
• Collaborative Filtering: Traditional "Users Like You Watched" recommendations powered by cypher traversal.
• TOPSIS Algorithm: A mathematical model (Technique for Order of Preference by Similarity to Ideal Solution) used to rank default recommendations based on user tags.

🎬 Movie Discovery & Exploration

• Comprehensive Movie Details: Deep metadata including synopsis, budget, revenue, runtime, release date, and original language.
• Rich Media: Integrated YouTube facade for watching official trailers, behind-the-scenes footage, and cast interviews.
• Cast & Crew Insights: Dedicated sections and full filmography pages for top cast and key crew members.

🎨 Premium UI/UX Design

• Cinematic Aesthetic: A sleek dark theme utilizing zinc and indigo/purple color palettes.
• Distinct Semantic Sections: Hero sections feature glowing gradients and unique SVG textures (Blueprint Grid for AI, Hexagons for Popular Cast, Dotted Grid for Top Rated) to distinctively mark different areas of the application.
• Dynamic Micro-animations: Smooth glassmorphism hover effects, backdrop gradients, and micro-animations for a premium, responsive feel.

---

🛠️ Technology Stack

Layer	Technologies
Frontend	React 19, Vite, TypeScript, Redux Toolkit, React Router v7, Tailwind CSS, shadcn/ui
Primary Backend (Go)	Go 1.24, Gin Web Framework, JWT Auth, LangChainGo, Redis
Recommendation Engine (Python)	Python 3, gRPC / Protocol Buffers, FastAPI, sentence-transformers
Databases	MongoDB, Neo4j, Redis (for real-time tag decay)

---

🚀 Getting Started

Prerequisites

• Node.js & npm (for the React Client)
• Go 1.24+ (for the Movie Server)
• Python 3.x (for the Recommendation Server)
• MongoDB (Local or Atlas instance)
• Neo4j (Local Desktop or AuraDB instance)
• Redis (Local or Cloud instance for user tags)

Setup Instructions

1. Movie Server (Go)

cd server/movie_server
# Copy the environment template and fill in your MongoDB URI, Gemini API key, and JWT secrets
cp .env.example .env
# Download dependencies
go mod download
# The server will automatically load the AI logic from prompts.json on startup
# Run the server on default port 8000
go run main.go

2. Recommendation Server (Python)

cd server/recommendation_server
# Copy the environment template and fill in your Neo4j passwords
cp .env.example .env
# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# (Optional) Compile gRPC proto files if you modify them:
# python -m grpc_tools.protoc -I../../proto --python_out=app/grpc --grpc_python_out=app/grpc ../../proto/search.proto
# Run the gRPC/FastAPI server
uvicorn main:app --reload --port 8001

3. Client (React/Vite)

cd "Client/Movie reviews"
# Install dependencies
npm install
# Run the development server
npm run dev