Personalized movie and TV show recommendations powered by your taste profile — rate what you've seen, discover what you'll love.
- Taste Profile Engine — Builds a multi-dimensional profile from your ratings across genres, directors, actors, keywords, decades, studios, and runtime preferences
- 7-Pipeline Recommendation System — Combines similar-to-loved, director/actor discovery, genre exploration, hidden gems, trending, and wildcard pipelines with diversity re-ranking
- Score Every Movie — Each recommendation gets a match percentage based on genre fit, keyword tone, director/actor familiarity, quality, decade preference, and 10+ penalty signals
- Find Me Something Like... — Search for any movie or TV show and get similar titles ranked by your taste, powered by TMDB similar + recommendations + genre/keyword discover
- What To Watch — Filter by genre, era, rating, runtime, or mood presets to discover movies tailored to your current vibe
- Mood Board — Pick a mood (Cozy Night In, Adrenaline Rush, Mind Blown, etc.) and get instant recommendations
- Movie Night — Group decision helper for picking a movie everyone will enjoy
- Compare — Put two titles side-by-side with detailed score breakdowns and a verdict on which fits your taste better
- Watchlist — Save movies to watch later with sorting, filtering, and taste-ranked ordering
- Letterboxd Import — Import your full watch history and ratings from Letterboxd CSV exports
- Movies & TV Shows — Full support for both movies and TV series across all features with proper TMDB endpoint routing
- Upcoming Releases — Browse upcoming movies with genre filters, time range, and a Most Anticipated section
- Browse Categories — Popular, Top Rated, Now Playing, Trending, and Hidden Gems with filters and taste scoring on every card
- Stats Dashboard — Visualize your rating distribution, genre preferences, decade trends, and watch history
- Firebase Auth & Sync — Optional cloud sync with Google authentication
| Tool | Version |
|---|---|
| Node.js | >= 18 |
| npm | Latest |
| TMDB API Key | Get one free |
# Clone the repository
git clone https://github.com/markksantos/movie-picker.git
cd movie-picker
# Install dependencies
npm install
# Start the development server
npm run devOn first launch, the app will ask for your TMDB API key — paste it in and you're ready to go.
npm run build
npm run preview| Category | Technology |
|---|---|
| Framework | React 19 |
| Build Tool | Vite 8 |
| Styling | Tailwind CSS 4 |
| Animation | Framer Motion 12 |
| Routing | React Router DOM 7 |
| State Management | Zustand 5 |
| Backend | Firebase (Auth, Firestore) |
| Movie Data | TMDB API |
movie-picker/
├── src/
│ ├── components/ # Shared UI (MovieCard, GenreTag, Toast, etc.)
│ ├── hooks/ # Custom hooks (useRecommendations)
│ ├── lib/
│ │ ├── recommender.js # 7-pipeline recommendation engine
│ │ ├── scorer.js # Multi-dimensional taste scoring
│ │ ├── profileBuilder.js # Taste profile from ratings
│ │ ├── diversifier.js # MMR diversity re-ranking
│ │ ├── tmdb.js # TMDB API client with caching
│ │ └── letterboxd.js # Letterboxd CSV import
│ ├── pages/ # All route pages (21 pages)
│ ├── stores/
│ │ ├── movieStore.js # Ratings, watchlist, dismissed (persisted)
│ │ ├── appStore.js # Settings, API key, weights
│ │ └── cacheStore.js # Recommendation cache & pipeline state
│ ├── App.jsx # Router, sidebar, bottom nav
│ └── main.jsx # Entry point
├── index.html
├── vite.config.js
└── package.json
MIT License © 2025 Mark Santos