Popcorn Wagon

A Personalized Movie Recommendation Platform

A hybrid recommender system powered by Flask, TMDB API, and MovieLens data.

Video Demo: Watch on YouTube
GitHub Repo: github.com/frissonitte/popcorn-wagon

---

Table of Contents

• About
• Features
• Getting Started
  • Prerequisites
  • Installation
• Project Structure
• Reflections
• Roadmap
• License
• Acknowledgments
• Powered By

---

About

Popcorn Wagon is a Flask-powered web application that helps users discover and manage movies they love. It leverages a hybrid recommendation engine that combines:

• Content-based filtering (TMDB API)
• Collaborative filtering (MovieLens + SVD + Annoy)

---

Features

• Search movies via the TMDB API
• View movie details: posters, genres, overviews
• Like/dislike movies and add custom tags
• Create and manage personalized movie lists
• Hybrid AI-powered recommendations using SVD + Annoy
• User authentication and session management
• Responsive UI built with Bootstrap 5
• Login and register functionality with secure session management

---

Getting Started

Prerequisites

• Python 3.x
• Flask
• SQLite
• TMDB API Key (stored in a .env file as TMDB_API_KEY) (Also set a secure SECRET_KEY for Flask sessions)

Installation

# Clone the repository
git clone https://github.com/frissonitte/popcorn-wagon.git
cd popcorn-wagon

# (Optional) Set up a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Dataset Setup

1. Download the full MovieLens dataset:
   https://grouplens.org/datasets/movielens/latest/

2. Place these files in app/data/:

   • links.csv
   • ratings.csv
   • tags.csv

3. Remove gnome-tags.csv and gnome-scores.csv if included.

Build the App

# (Optional) Clean and filter active users
python filter_csv.py

# Initialize the SQLite database
python data_loader.py

# Train the recommendation model
python train_model.py

# Run the Flask app
python run.py  # or use: flask run

Then open your browser to:
http://127.0.0.1:5000

---

Project Structure

popcorn-wagon/
├── app/
│   ├── data/             # MovieLens dataset
│   ├── static/           # CSS, JS, images
│   ├── templates/        # HTML templates
│   ├── utils/            # Utility scripts
│   ├── routes.py         # Main views
│   ├── auth.py           # Login/register
│   ├── models.py         # SQLAlchemy models
│   └── extensions.py     # Flask extensions
├── instance/             # SQLite DB
├── .env                  # Your API keys
├── train_model.py        # SVD + Annoy trainer
├── filter_csv.py         # Dataset cleaner
├── data_loader.py        # DB initializer
├── run.py                # App entry point
├── requirements.txt
└── README.md

---

Reflections

This project taught me:

• Flask routing, sessions, and form handling
• Designing normalized SQL databases with SQLAlchemy
• Building hybrid recommender systems
• Using SVD + Annoy for fast similarity searches
• Data cleaning and optimization with Pandas and Dask

---

Roadmap

Planned enhancements:

• UI/UX overhaul
• REST API support
• OAuth login (e.g. Google)
• TMDB/IMDB list import
• Shareable movie lists
• Dark mode

---

License

MIT License — See LICENSE for details.

---

Acknowledgments

• CS50 team — for the CS foundation
• MovieLens — for the public dataset
• TMDB — for the movie metadata API
• Flask & SQLAlchemy — backend technologies

---

🔌 Powered By

MovieLens, Flask, Annoy, SVD, Dask