Project 24: Movie Database Matchmaker

📋 Project Brief

Build a movie discovery application using the TMDB API. Users can search, filter, and save movies to a watchlist. The app features infinite scroll for results, trailer embedding, and an actor filmography deep-dive.

✅ Feature Requirements

Feature 1: Multi-Filter Search

Acceptance Criteria:

• Filter simultaneously by: genre (multi-select), year range (slider), minimum rating (slider)
• Filters are reflected in the URL query params (shareable/bookmarkable)
• A "Clear Filters" button resets all filters
• Results update in real-time as filters change (debounced by 300ms)
• Show result count: "Found 2,847 movies"

Feature 2: Watchlist

Acceptance Criteria:

• A "Save" button on each movie card adds it to the watchlist
• Watchlist is stored in localStorage
• A dedicated "My Watchlist" page shows all saved movies
• Movies can be removed from the watchlist
• Watchlist badge in the header shows the count

Feature 3: Trailer Integration

Acceptance Criteria:

• Movie detail pages embed the official YouTube trailer
• The trailer loads in a responsive iframe (16:9 aspect ratio)
• If no trailer exists, show a "No trailer available" placeholder
• A "Watch Trailer" button on the movie card opens a modal with the embedded video

Feature 4: Actor Deep-Dive

Acceptance Criteria:

• Clicking an actor's name on a movie page shows their complete filmography
• Filmography sorted by year (most recent first)
• Each movie in the filmography is clickable (navigates to that movie's detail page)
• Show actor bio, photo, and known-for movies

Feature 5: Infinite Scroll

Acceptance Criteria:

• Search results load 20 movies at a time
• Scrolling to the bottom triggers the next page fetch
• Use Intersection Observer (not scroll events)
• Show a loading spinner while fetching
• Handle API pagination correctly (TMDB uses page numbers)

📊 API Endpoints to Use (TMDB)

Endpoint	Purpose
/discover/movie	Filter by genre, year, rating
/search/movie	Search by title
/movie/{id}	Movie details
/movie/{id}/videos	Trailers
/movie/{id}/credits	Cast and crew
/person/{id}	Actor details
/person/{id}/movie_credits	Actor filmography

🧪 Testing Checklist

• Unit test URL query param generation from filter state
• Unit test watchlist add/remove/check logic
• Mock API responses for movie search, details, and credits
• Integration test: applying filters updates results
• A11y: movie cards have descriptive alt text; modals trap focus

🚀 Stretch Goals

• Add a "Recommendation Engine" — "Because you saved X, you might like Y"
• Implement a "Mood Matcher" — select an emoji and get genre suggestions
• Add movie ratings/reviews by the user
• Create a "Movie Night Randomizer" from the watchlist