PopChoice

PopChoice is a movie recommendation engine that uses AI embeddings and vector databases to provide personalized movie suggestions based on user preferences.

This is a solo project for the Embeddings and Vector Databases chapter from "The AI Engineer Path" on Scrimba.

✨ Features

• 🎬 AI-Powered Recommendations - Uses OpenAI embeddings for semantic movie matching
• 📊 Interactive Questionnaire - Collects user preferences through engaging questions
• 🔍 Vector Search - Lightning-fast similarity search with Supabase pgvector
• 📱 Responsive Design - Works seamlessly on desktop and mobile
• 🧪 Component Library - Built with Storybook for consistent UI components

🛠 Tech Stack

• Frontend: Next.js 15, React 19, TypeScript, Tailwind CSS
• AI/ML: OpenAI GPT & Embeddings API
• Database: Supabase (PostgreSQL with pgvector extension)
• Movie Data: TMDB (The Movie Database) API
• Analytics: Vercel Web Analytics
• Testing: Vitest, Storybook, Playwright
• Development: ESLint, Prettier, Husky, lint-staged

🚀 Quick Start

1. Clone and install dependencies

   git clone <repository-url>
   cd PopChoice
   npm install

2. Set up environment variables

   cp .env.example .env
   # Edit .env with your API keys

   For detailed setup instructions, see the Setup Guide.

3. Start development server

   npm run dev

4. Open the application

   • Navigate to http://localhost:3000
   • Start the Storybook workshop at http://localhost:6006 with npm run storybook

📖 Documentation

• Setup Guide - Complete setup instructions for OpenAI, Supabase, and development environment
• Development Guide - Development workflows, scripts, and project structure
• CI/CD Documentation - GitHub Actions workflow and deployment information

🗂 Project Structure

src/
├── app/                    # Next.js app directory
│   ├── api/               # API routes (movie recommendations)
│   └── pages/             # Application pages
├── components/            # Reusable React components
│   ├── QuestionsForm/     # Movie preference questionnaire
│   ├── SuggestionCard/    # Movie recommendation cards
│   └── ...               # Other UI components
├── services/              # External API integrations
│   └── MovieService/      # TMDB API integration
└── utils/                 # Utility functions
    ├── db/               # Database schemas and functions
    └── movies/           # Movie data processing utilities

🧪 Development Scripts

# Development
npm run dev              # Start development server
npm run build           # Build for production
npm run start           # Start production server

# Testing
npm run test            # Run all tests
npm run test:server     # Run utility function tests
npm run test:storybook  # Component tests (browser environment)
npm run storybook       # Start component workshop

# Code Quality
npm run lint:check      # Check code quality
npm run format:check    # Check formatting
npm run type-check      # TypeScript validation
npm run fix             # Fix all issues automatically

# Database & Data
npm run populate-db     # Populate database with movie data
npm run analyze-movies  # Analyze movie data for embeddings

For detailed development workflows and project structure, see the Development Guide.

🔗 Learn More

• Next.js Documentation - Learn about Next.js features and API
• OpenAI Embeddings Guide - Understanding embeddings for recommendations
• Supabase Vector Documentation - Vector database setup
• TMDB API Documentation - The Movie Database API integration
• The AI Engineer Path - Complete AI engineering course

🚀 Deploy on Vercel

The easiest way to deploy your Next.js app is to use the Vercel Platform.

Check out the Next.js deployment documentation for more details.

---

Built with ❤️ for learning AI engineering