🎬 Movie Recommendation System (Python + Flask + TMDB API + Gemini AI)

A dynamic Movie Recommendation Website built using Python (Flask) for the backend and HTML, CSS, and JavaScript for the frontend. It recommends movies based on user preferences (genres, actors, films) and AI-powered vibes, fetching live data from The Movie Database (TMDB) API and Google Gemini AI.

---

🎯 Project Overview

WatchIT is a sophisticated movie discovery platform that combines multiple recommendation strategies:

1. Genre + Actor Filtering - Traditional filtering with concurrent API calls
2. Similar Movies - Find movies similar to ones you love
3. AI Vibe Check - Describe a mood/vibe and let AI find perfect matches
4. Trending Movies - Browse what's popular this week
5. Personal Watchlist - Save movies locally (localStorage)

---

🏗️ End-to-End Architecture

System Overview Diagram

┌─────────────────────────────────────────────────────────────┐
│                    Frontend (Browser)                        │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  HTML Template (index.html)                         │   │
│  │  - Trending Movies Grid                             │   │
│  │  - Discovery Engine (Genres, Actors, Movies)        │   │
│  │  - AI Vibe Input                                    │   │
│  │  - Results Grid with Pagination                     │   │
│  │  - Watchlist Section                                │   │
│  └─────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  JavaScript (script.js)                             │   │
│  │  - Fetch & Display Data                             │   │
│  │  - Pagination Logic                                 │   │
│  │  - Watchlist State Management (localStorage)        │   │
│  │  - Event Handlers                                   │   │
│  └─────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  CSS (style.css)                                    │   │
│  │  - Glassmorphism Design                             │   │
│  │  - Responsive Grid Layout                           │   │
│  │  - Dark Theme with Red Accents                      │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                          ↓
                    HTTP Requests
                          ↓
┌─────────────────────────────────────────────────────────────┐
│                Flask Backend (Python)                        │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  app.py - Core Application Logic                    │   │
│  │  ├── Route: GET /                                   │   │
│  │  ├── Route: GET /api/trending                       │   │
│  │  ├── Route: POST /recommend                         │   │
│  │  └── Route: POST /api/vibe                          │   │
│  └─────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  Helper Functions                                   │   │
│  │  ├── safe_request() - Error Handling                │   │
│  │  ├── search_actor() - TMDB Person Search            │   │
│  │  ├── search_movie() - TMDB Movie Search             │   │
│  │  ├── discover_movies() - Multi-filter Discovery     │   │
│  │  ├── get_similar_movies() - Similarity Search       │   │
│  │  ├── format_movie_results() - Data Formatting       │   │
│  │  └── get_genre_list() - Genre Metadata              │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
         ↓                                    ↓
   ┌──────────┐                      ┌──────────────┐
   │ TMDB API │◄──────────────────►  │  Gemini AI   │
   │(Movie DB)│  (for AI searches)   │ (for vibes)  │
   └──────────┘                      └──────────────┘

---

🚀 Features

1. Trending Movies Section 📺

• Fetches the 12 most popular movies of the week from TMDB
• Displays on page load automatically
• Shows full movie details: poster, rating, release date, overview

2. Discovery Engine 🔍

• Genre Selection: Browse and select multiple genres
• Actor Search: Type actor names (auto-searched on TMDB)
• Movie Search: Find movies similar to your favorites
• Pagination: Browse through 18 results per page
• Multi-threading: Actor and similar movie searches run concurrently for speed

3. AI Vibe Check ✨

• Natural language movie search powered by Google Gemini AI
• Example inputs: "A visually stunning sci-fi with a plot twist"
• AI picks 6 movies, then fetches real TMDB data for them
• Includes AI-generated explanations for each recommendation

4. Watchlist Management 📝

• Save movies from any section (trending, search results, AI recommendations)
• Persists data locally using browser's localStorage
• Toggle movies in/out of watchlist easily
• View all saved movies in the dedicated watchlist section

5. Responsive UI 💅

• Dark theme with cinematic red accents (Netflix-inspired)
• Glassmorphism design with frosted glass effects
• Sticky navigation bar
• Responsive grid layout (adapts to screen size)
• Smooth scrolling and animations

---

🧠 Tech Stack

Component	Technology	Purpose
Backend	Python 3 + Flask	REST API & Request Handling
Frontend	HTML5, CSS3, Vanilla JS	UI & User Interactions
Movie Data	TMDB API v3	Real-time movie database
AI Engine	Google Generative AI (Gemini 2.5 Flash)	Natural language recommendations
Concurrency	Python concurrent.futures	Multi-threaded API calls
Env Config	python-dotenv	API key management
HTTP Client	Python requests	API communication
Deployment	Render + Gunicorn	Production hosting

---

📦 Project Structure

Movie-Recommender/
├── app.py                    # Flask application & API routes
├── requirements.txt          # Python dependencies
├── README.md                 # This file
├── movies.csv               # Legacy movie data (reference)
├── .env                     # Environment variables (TMDB_API_KEY, GEMINI_API_KEY)
│
├── templates/
│   └── index.html           # Main HTML template
│
└── static/
    ├── style.css            # Styling & glassmorphism design
    └── script.js            # Frontend logic & API interactions

---

🔧 Installation & Setup

Prerequisites

• Python 3.8+
• API Keys from:
  • TMDB API (free tier available)
  • Google Generative AI (free tier)

Step 1: Clone & Install

# Clone the repository
git clone https://github.com/your-username/Movie-Recommender.git
cd Movie-Recommender

# Create virtual environment (optional but recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Step 2: Configure API Keys

Create a .env file in the root directory:

TMDB_API_KEY=your_tmdb_api_key_here
GEMINI_API_KEY=your_gemini_api_key_here

Step 3: Run the Application

python app.py

Open your browser and go to: http://localhost:5000

---

💻 Implementation Details

Backend: Flask Application (app.py)

1. Initialization

from flask import Flask, render_template, request, jsonify
import requests
import google.generativeai as genai
from dotenv import load_dotenv

app = Flask(__name__)
load_dotenv()  # Load API keys from .env file

API_KEY = os.getenv("TMDB_API_KEY")
BASE_URL = "https://api.themoviedb.org/3"
GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")

2. Error Handling: safe_request() Function

Wraps all API calls with try-catch to prevent crashes:

def safe_request(url, params=None):
    try:
        response = requests.get(url, params=params, timeout=8)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"⚠️ API connection error: {e}")
        return {}  # Return empty dict instead of crashing

Why? If TMDB is down or the network fails, the app gracefully returns empty results instead of breaking.

3. Data Fetching Functions

get_genre_list() - Fetches all available genres

def get_genre_list():
    url = f"{BASE_URL}/genre/movie/list"
    data = safe_request(url, {"api_key": API_KEY})
    return data.get("genres", [])

Used to populate the genre checkboxes on page load.

search_actor(actor_name) - Converts actor name to TMDB ID

def search_actor(actor_name):
    url = f"{BASE_URL}/search/person"
    data = safe_request(url, {"api_key": API_KEY, "query": actor_name})
    if data.get("results"):
        return data["results"][0]["id"]  # Returns first match
    return None

search_movie(movie_name) - Converts movie title to TMDB ID

def search_movie(movie_name):
    url = f"{BASE_URL}/search/movie"
    data = safe_request(url, {"api_key": API_KEY, "query": movie_name})
    if data.get("results"):
        return data["results"][0]["id"]
    return None

discover_movies(genres, actors, page) - Filters movies by genre/actor combo

def discover_movies(genres=None, actors=None, page=1):
    params = {
        "api_key": API_KEY,
        "sort_by": "popularity.desc",  # Sort by most popular
        "page": page
    }
    if genres:
        params["with_genres"] = ",".join(map(str, genres))  # "28,12,16"
    if actors:
        params["with_cast"] = ",".join(map(str, actors))    # "1,2,3"
    
    data = safe_request(f"{BASE_URL}/discover/movie", params)
    return format_movie_results(data)

get_similar_movies(movie_id, page) - Fetches movies similar to a given title

def get_similar_movies(movie_id, page=1):
    url = f"{BASE_URL}/movie/{movie_id}/similar"
    data = safe_request(url, {"api_key": API_KEY, "page": page})
    return format_movie_results(data)

format_movie_results(data) - Standardizes API response into consistent format

def format_movie_results(data):
    results = []
    for m in data.get("results", []):
        poster = f"https://image.tmdb.org/t/p/w500{m['poster_path']}" \
                 if m.get("poster_path") else ""
        results.append({
            "title": m.get("title", "Unknown"),
            "overview": m.get("overview", "No description available."),
            "poster": poster,  # Full URL for image
            "release_date": m.get("release_date", "N/A"),
            "rating": m.get("vote_average", 0)
        })
    return results

4. API Routes

GET / - Home page with genres pre-loaded

@app.route('/')
def home():
    genres = get_genre_list() or []
    return render_template('index.html', genres=genres)

GET /api/trending - Trending movies for the week

@app.route('/api/trending', methods=['GET'])
def get_trending():
    url = f"{BASE_URL}/trending/movie/week"
    data = safe_request(url, {"api_key": API_KEY})
    return jsonify(format_movie_results(data)[:12])  # Top 12

POST /recommend - Main recommendation engine with multi-threading

@app.route('/recommend', methods=['POST'])
def recommend_movies():
    try:
        data = request.get_json()
        genres = data.get("genres", [])
        actors = [a.strip() for a in data.get("actors", []) if a.strip()]
        movies = [m.strip() for m in data.get("movies", []) if m.strip()]
        page = int(data.get("page", 1))

        all_results = []

        # --- CONCURRENT API CALLS FOR SPEED ---
        with concurrent.futures.ThreadPoolExecutor() as executor:
            # Fetch all actor IDs in parallel
            if actors:
                actor_ids = list(executor.map(search_actor, actors))
                actor_ids = [a for a in actor_ids if a]  # Clean Nones
            else:
                actor_ids = []

            # Get genre/actor recommendations
            if genres or actor_ids:
                all_results.extend(discover_movies(genres=genres, 
                                                    actors=actor_ids, 
                                                    page=page))

            # Fetch similar movies in parallel
            if movies:
                movie_ids = list(executor.map(search_movie, movies))
                movie_ids = [mid for mid in movie_ids if mid]
                
                # Submit all similar movie requests concurrently
                futures = [executor.submit(get_similar_movies, mid, page) 
                          for mid in movie_ids]
                for future in concurrent.futures.as_completed(futures):
                    all_results.extend(future.result())

        if not all_results:
            return jsonify({"error": "Could not fetch recommendations."}), 200

        # Remove duplicates while preserving order
        seen = set()
        unique_results = []
        for r in all_results:
            if r["title"] not in seen:
                seen.add(r["title"])
                unique_results.append(r)

        return jsonify(unique_results[:18])  # Return top 18 results

    except Exception as e:
        print(f"Server Error: {e}")
        return jsonify({"error": "An error occurred while fetching movies."}), 500

Key optimization: Uses ThreadPoolExecutor to search for multiple actors and similar movies simultaneously instead of waiting for each one.

POST /api/vibe - AI-powered recommendation with Gemini

@app.route('/api/vibe', methods=['POST'])
def vibe_search():
    data = request.get_json()
    vibe_prompt = data.get("vibe", "").strip()

    if not vibe_prompt:
        return jsonify({"error": "Please enter a vibe."}), 400

    try:
        # 1. Ask AI to pick 6 movies matching the vibe
        prompt = f"""
        You are an expert movie curator. The user wants movies with this vibe/description: "{vibe_prompt}"
        Recommend exactly 6 movies that perfectly match.
        Return ONLY a raw JSON array. Do NOT wrap it in markdown.
        Each object must have exactly two keys:
        "title": "The exact official movie title",
        "ai_reason": "A 1-sentence explanation of why it fits."
        """

        response = model.generate_content(prompt)
        
        # 2. Clean the AI response (sometimes it wraps in ```json)
        raw_text = response.text.strip()
        if raw_text.startswith("```"):
            raw_text = raw_text.split("\n", 1)[-1]
        if raw_text.endswith("```"):
            raw_text = raw_text.rsplit("\n", 1)[0]
        
        ai_recommendations = json.loads(raw_text)

        # 3. Fetch real TMDB data for AI-selected movies
        final_results = []
        for rec in ai_recommendations:
            url = f"{BASE_URL}/search/movie"
            tmdb_data = safe_request(url, {"api_key": API_KEY, 
                                           "query": rec["title"]})
            
            if tmdb_data and tmdb_data.get("results"):
                m = tmdb_data["results"][0]  # Top match
                poster = f"https://image.tmdb.org/t/p/w500{m['poster_path']}" \
                        if m.get("poster_path") else ""
                final_results.append({
                    "title": m.get("title", rec["title"]),
                    "overview": m.get("overview", "No description"),
                    "poster": poster,
                    "release_date": m.get("release_date", "N/A"),
                    "rating": m.get("vote_average", 0),
                    "ai_reason": rec.get("ai_reason", "")
                })

        return jsonify(final_results)

    except Exception as e:
        print(f"⚠️ AI Error: {e}")
        return jsonify({"error": "The AI curator is resting. Try again!"}), 500

Workflow: AI suggests titles → Search TMDB for exact matches → Merge AI reasons with real movie data

---

Frontend: HTML Template (templates/index.html)

Key Sections

1. Navigation Bar

   • Logo with movie icon
   • Links to "Explore" and "Watchlist"

2. Trending Movies Grid

   • Auto-loaded on page load
   • 12-movie grid display
   • Watchlist toggle button on each card

3. Discovery Engine Panel

   • Genre checkboxes (from backend)
   • Text inputs for actors and movies (comma-separated)
   • AI Vibe input with "Ask AI" button
   • Main "Generate Watchlist" button

4. Results Section

   • Dynamic movie grid
   • Pagination controls (Prev/Next)
   • Watchlist toggle per card

5. Watchlist Section

   • Persistent display of saved movies
   • Located below results

---

Frontend: JavaScript Logic (static/script.js)

State Management

let currentApiPage = 1;           // Pagination tracking
let lastResults = [];             // Latest search results
let trendingResults = [];         // Trending movies cache
let watchlist = JSON.parse(localStorage.getItem('myWatchlist')) || [];  // Persistent watchlist

Key Functions

fetchTrendingMovies() - Loads trending movies on page load

async function fetchTrendingMovies() {
    try {
        const response = await fetch("/api/trending");
        const data = await response.json();
        
        if (Array.isArray(data) && data.length > 0) {
            trendingResults = data;
            renderTrending();
        }
    } catch (error) {
        console.error("Error fetching trending:", error);
    }
}

getRecommendations(page) - Fetches genre/actor/movie recommendations

async function getRecommendations(page = 1) {
    currentApiPage = page;
    const genres = Array.from(document.querySelectorAll('input[name="genre"]:checked'))
                         .map(el => el.value);
    const actors = document.getElementById('actors').value
                          .split(',')
                          .map(a => a.trim())
                          .filter(a => a !== "");
    const movies = document.getElementById('movies').value
                          .split(',')
                          .map(m => m.trim())
                          .filter(m => m !== "");

    document.getElementById("results-section").style.display = "block";
    document.getElementById("results").innerHTML = "<p>Loading...</p>";

    try {
        const response = await fetch("/recommend", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ 
                genres, 
                actors, 
                movies, 
                page 
            })
        });

        const data = await response.json();
        lastResults = data;
        renderResults();

    } catch (error) {
        console.error("Error:", error);
        document.getElementById("results").innerHTML = "<p style='color:red;'>Network error</p>";
    }
}

getVibeRecommendations() - Calls AI vibe endpoint

async function getVibeRecommendations() {
    const vibeText = document.getElementById('vibe-input').value.trim();
    if (!vibeText) return alert("Please enter a vibe first!");

    const resultsSection = document.getElementById("results-section");
    const container = document.getElementById("results");

    resultsSection.style.display = "block";
    container.innerHTML = `<p style="color: var(--accent-red);">
        <i class="fas fa-spinner fa-spin"></i> Our AI is searching...
    </p>`;

    try {
        const response = await fetch("/api/vibe", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ vibe: vibeText })
        });

        const data = await response.json();
        if (data.error) {
            container.innerHTML = `<p style="color:red;">${data.error}</p>`;
            return;
        }

        container.innerHTML = "";
        data.forEach(m => container.appendChild(createDetailedMovieCard(m)));

    } catch (error) {
        container.innerHTML = `<p style="color:red;">Network error</p>`;
    }
}

toggleWatchlist(title) - Add/remove from watchlist with persistence

function toggleWatchlist(title) {
    // Search in all three result sources
    const movie = lastResults.find(m => m.title === title) ||
                  trendingResults.find(m => m.title === title) ||
                  watchlist.find(m => m.title === title);

    if (!movie) return;

    const index = watchlist.findIndex(m => m.title === title);

    if (index !== -1) {
        watchlist.splice(index, 1);  // Remove if exists
    } else {
        watchlist.push(movie);  // Add if doesn't exist
    }

    // Persist to localStorage
    localStorage.setItem('myWatchlist', JSON.stringify(watchlist));
    
    // Update UI
    renderWatchlist();
    updateMovieCardUI(title);  // Update all instances
}

renderWatchlist() - Display saved movies

function renderWatchlist() {
    const container = document.getElementById("watchlist-results");
    container.innerHTML = "";

    if (watchlist.length === 0) {
        container.innerHTML = "<p style='color:var(--text-muted);'>Your watchlist is empty</p>";
        return;
    }

    watchlist.forEach(m => {
        container.appendChild(createDetailedMovieCard(m));
    });
}

Movie Card Creation - Generates dynamic HTML for each movie

function createDetailedMovieCard(movie) {
    const card = document.createElement("div");
    card.className = "movie-card";
    card.innerHTML = `
        <div class="card-image">
            <img src="${movie.poster}" alt="${movie.title}">
        </div>
        <div class="card-content">
            <h3>${movie.title}</h3>
            <p class="rating">⭐ ${movie.rating}</p>
            <p class="release-date">${movie.release_date}</p>
            <p class="overview">${movie.overview.substring(0, 100)}...</p>
            ${movie.ai_reason ? `<p class="ai-reason">🤖 ${movie.ai_reason}</p>` : ""}
            <button class="watchlist-btn" onclick="toggleWatchlist('${movie.title}')">
                ${isInWatchlist(movie.title) ? '❌ Remove' : '➕ Add'}
            </button>
        </div>
    `;
    return card;
}

---

Frontend: Styling (static/style.css)

Design Philosophy

• Glassmorphism: Frosted glass effect with backdrop-filter: blur()
• Dark Theme: Base color #0d0d12 (deep dark)
• Accent Color: Netflix red #E50914
• Typography: Inter font family with 400/600/800 weights

Key CSS Features

Glassmorphism Nav

.navbar {
    background-color: var(--glass-bg);  /* rgba(35, 35, 45, 0.3) */
    backdrop-filter: blur(16px);
    -webkit-backdrop-filter: blur(16px);
    border-bottom: 1px solid var(--glass-border);
    box-shadow: 0 4px 30px rgba(0, 0, 0, 0.3);
}

Responsive Grid

.movie-grid {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(180px, 1fr));
    gap: 20px;
    margin-bottom: 40px;
}

Animated Background

body {
    background-image:
        radial-gradient(circle at 10% 10%, rgba(229, 9, 20, 0.12) 0%, transparent 40%),
        radial-gradient(circle at 90% 90%, rgba(229, 9, 20, 0.08) 0%, transparent 40%);
    background-attachment: fixed;
}

---

🚀 How the Data Flows

Scenario 1: User Selects Genres + Actor

User Input (Frontend)
    ↓
JavaScript fetches /recommend with genres=[28, 12] & actors=["Tom Hanks"]
    ↓
Flask Backend processes request
    ↓
1. Search "Tom Hanks" → Get ID: 2500
2. Call /discover/movie with genres=28,12 & with_cast=2500
    ↓
TMDB API returns 20 movies
    ↓
Format results (add poster URLs, clean data)
    ↓
Return JSON array with 18 movies (top results, no duplicates)
    ↓
JavaScript renders movie grid with pagination
    ↓
User can toggle watchlist (saved to localStorage)

Scenario 2: User Enters AI Vibe

User Input: "A visually stunning sci-fi with a plot twist"
    ↓
JavaScript fetches /api/vibe with vibe text
    ↓
Flask Backend calls Google Gemini AI
    ↓
AI responds: [{"title": "Inception", "ai_reason": "..."}, ...]
    ↓
For each AI suggestion:
  1. Search TMDB for the movie
  2. Fetch real poster, rating, overview
  3. Merge with AI reason
    ↓
Return combined JSON with AI explanations + real data
    ↓
JavaScript renders results with AI reasons visible

Scenario 3: Watchlist Persistence

User clicks "Add to Watchlist"
    ↓
toggleWatchlist(title) called
    ↓
Movie object added to watchlist array
    ↓
Array saved to browser's localStorage: 'myWatchlist'
    ↓
Page refreshes or closed/reopened
    ↓
JavaScript loads: JSON.parse(localStorage.getItem('myWatchlist'))
    ↓
Watchlist persists (no backend required)

---

🔑 Key Technical Decisions

1. Multi-Threading for Performance

with concurrent.futures.ThreadPoolExecutor() as executor:
    actor_ids = list(executor.map(search_actor, actors))

• Why? Searching 5 actors sequentially = 5× API calls waiting time
• With threading? All 5 requests fire simultaneously → ~1/5 the wait time
• Trade-off: Marginally higher CPU; much faster UX

2. Safe Request Wrapper

def safe_request(url, params=None):
    try:
        ...
    except requests.exceptions.RequestException:
        return {}  # Return empty dict

• Why? Prevents complete app crash if external API fails
• User experience: Graceful error message instead of 500 error

3. Duplicate Removal

seen = set()
for r in all_results:
    if r["title"] not in seen:
        unique_results.append(r)
        seen.add(r["title"])

• Why? Same movie can appear in multiple recommendation sources
• Approach: Use set for O(1) lookup instead of O(n)

4. localStorage for Watchlist

• Why not database? This is a recommendation engine, not a user system
• Benefit: Works offline, no backend storage needed
• Trade-off: Data is local to one browser, not synced across devices

5. AI + TMDB Hybrid

• Why two APIs? AI is creative but doesn't know current ratings/posters
• Solution: AI picks movie titles → TMDB provides real data → merge results
• Robustness: If AI hallucinates a movie, TMDB search returns nothing gracefully

---

🚦 Error Handling Strategy

Error	Handling
API Connection Fail	safe_request() returns {}
Invalid Genre ID	Skipped silently (filtered out)
Actor Not Found	None returned, filtered from list
No Results	Returns {"error": "..."} JSON
AI Returns Invalid JSON	Caught, returns error message
Missing Poster	Empty string, CSS handles gracefully
Timeout	8-second timeout, returns empty result

---

📊 Performance Metrics

• Page Load: ~1-2 seconds (trending + genres)
• Genre Search: ~0.5s (depends on result count)
• Actor Search: ~0.3s per actor (multi-threaded: ~0.3s for 5 actors)
• AI Vibe Search: ~2-3s (Gemini API + TMDB search)
• Frontend Rendering: <0.1s (DOM insertion)

---

🔐 Security Considerations

1. API Keys in .env - Never committed to Git
2. HTTPS on Production - All APIs use HTTPS
3. CORS - Flask serves from same domain
4. Input Validation - Strips empty strings, validates page numbers
5. Timeout Protection - 8-second timeout on external API calls

---

📝 Dependencies

See requirements.txt for full list:

• Flask - Web framework
• requests - HTTP client
• python-dotenv - Environment variables
• google-generativeai - Gemini AI SDK
• gunicorn - Production server

---

🎓 Learning Outcomes

This project demonstrates:

• ✅ Full-stack web development (frontend + backend)
• ✅ RESTful API design
• ✅ Error handling & graceful degradation
• ✅ Concurrent programming (multi-threading)
• ✅ External API integration (TMDB, Gemini)
• ✅ Frontend state management (localStorage)
• ✅ Responsive UI design
• ✅ HTML templating (Jinja2)

---

🚀 Future Enhancements

• User authentication & cloud watchlist
• Movie ratings & reviews
• Advanced filters (year, budget, runtime)
• Streaming service availability (where to watch)
• Social features (share recommendations)
• Mobile app version
• Dark/light theme toggle

---

📄 License

This project is open source and available under the MIT License.

---

🤝 Contributing

Contributions are welcome! Feel free to submit issues and pull requests.

---

Made with ❤️ and 🎬