Movie Recommendation System

A full-stack movie recommendation system built with Flask (Python) and React, using collaborative filtering algorithms and MongoDB for data storage.

Features

• 🎬 Movie Recommendations: Get personalized movie recommendations based on user preferences
• 👤 User Profiles: View user statistics including movies rated, average rating, and favorite genres
• 🔍 Collaborative Filtering: Uses user-based collaborative filtering with cosine similarity
• 📊 MovieLens Dataset: Supports MovieLens 100k dataset (943 users, 1682 movies)

Dataset

This repository does not include the MovieLens dataset files. Download MovieLens 100k and extract it into the project root so you have a folder named ml-100k/ (it should contain files like u.data, u.item, etc.).

Project Structure

.
├── app.py                 # Flask API application
├── ml_recommend.py        # Recommendation algorithm implementation
├── movielens_loader.py    # Data loading script
├── database.py            # Database connection management
├── config.py              # Configuration management
├── requirements.txt       # Python dependencies
└── frontend/              # React frontend application
    ├── src/
    │   ├── App.js        # Main React component
    │   └── App.css       # Styles
    └── package.json      # Node.js dependencies

Prerequisites

• Python 3.8+
• Node.js 14+ and npm
• MongoDB Atlas account (or local MongoDB instance)
• Git

Installation

1. Clone the Repository

git clone https://github.com/Nitharshan369/movie-recommendation-system.git
cd Project

2. Backend Setup

1. Create a virtual environment (recommended):

python -m venv venv

# On Windows
venv\Scripts\activate

# On macOS/Linux
source venv/bin/activate

2. Install Python dependencies:

pip install -r requirements.txt

3. Configure environment variables:

Copy the example environment file and fill in your credentials:

# Copy the example file
cp .env.example .env
# Or on Windows:
copy .env.example .env

Then edit .env and replace the placeholder values with your actual MongoDB credentials:

MONGODB_USERNAME=your_username
MONGODB_PASSWORD=your_password
MONGODB_CLUSTER=your_cluster.mongodb.net
MONGODB_DATABASE=movie_recommendation

FLASK_ENV=development
FLASK_DEBUG=True
FLASK_HOST=127.0.0.1
FLASK_PORT=5000

CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

DEFAULT_TOP_N=5
DEFAULT_K_NEIGHBORS=10

⚠️ Important:

• If you don't have .env.example, create one based on the template above.

4. Download MovieLens 100k:

Download and extract MovieLens 100k from the official page: MovieLens 100k.

After extracting, you should have ml-100k/ in the project root.

5. Load MovieLens data into MongoDB:

python movielens_loader.py

This will populate your MongoDB database with movies and ratings from the MovieLens 100k dataset.

3. Frontend Setup

1. Navigate to frontend directory:

cd frontend

2. Install dependencies:

npm install

3. Configure API URL (optional):

Create a .env file in the frontend directory:

REACT_APP_API_URL=http://localhost:5000

If not set, the frontend defaults to http://127.0.0.1:5000.

Running the Application

Start the Backend

From the root directory:

python app.py

The API will be available at http://127.0.0.1:5000

Start the Frontend

From the frontend directory:

npm start

The frontend will be available at http://localhost:3000

API Endpoints

GET /

Health check endpoint.

Response:

{
  "status": "Movie Recommendation API running",
  "version": "1.0.0"
}

GET /ml-recommend/<user_id>

Get movie recommendations for a user.

Parameters:

• user_id (path): User ID (1-943)
• top_n (query, optional): Number of recommendations (default: 5, max: 50)
• k_neighbors (query, optional): Number of similar users (default: 10, max: 100)

Example:

GET /ml-recommend/1?top_n=10&k_neighbors=20

Response:

{
  "user_id": "1",
  "recommendations": [
    "Movie Title 1",
    "Movie Title 2",
    ...
  ],
  "count": 10
}

GET /user-profile/<user_id>

Get user profile information.

Parameters:

• user_id (path): User ID (1-943)
• top_n_genres (query, optional): Number of top genres (default: 3, max: 18)

Example:

GET /user-profile/1?top_n_genres=5

Response:

{
  "user_id": "1",
  "movies_rated": 272,
  "average_rating": 3.87,
  "top_genres": ["Action", "Drama", "Thriller"]
}

Usage Examples

Using cURL

# Get recommendations for user 1
curl http://localhost:5000/ml-recommend/1

# Get user profile
curl http://localhost:5000/user-profile/1

# Get 10 recommendations using 20 neighbors
curl http://localhost:5000/ml-recommend/1?top_n=10&k_neighbors=20

Using Python

import requests

# Get recommendations
response = requests.get("http://localhost:5000/ml-recommend/1")
recommendations = response.json()

# Get user profile
response = requests.get("http://localhost:5000/user-profile/1")
profile = response.json()

Algorithm Details

The recommendation system uses User-Based Collaborative Filtering:

1. User Similarity: Computes cosine similarity between users based on their movie ratings
2. Neighbor Selection: Finds the k most similar users (neighbors)
3. Recommendation Generation: Aggregates ratings from neighbors for movies the user hasn't rated
4. Ranking: Sorts movies by weighted scores and returns top N recommendations

Troubleshooting

Database Connection Issues

• Verify your MongoDB credentials in .env
• Check your network connection
• Ensure MongoDB Atlas IP whitelist includes your IP address

Frontend Can't Connect to Backend

• Ensure Flask is running on the correct port
• Check CORS configuration in config.py
• Verify REACT_APP_API_URL in frontend .env

No Recommendations Returned

• Ensure data is loaded: run python movielens_loader.py
• Verify user_id exists (1-943 for MovieLens 100k)
• Check database collections have data

Development

Code Structure

• Backend: Flask REST API with modular structure
• Frontend: React single-page application
• Database: MongoDB for flexible schema storage

Extending the System

• New API Endpoints: Add routes in app.py
• Algorithm Improvements: Modify functions in ml_recommend.py
• Frontend Features: Update components in frontend/src/

Security Notes

• Credentials stored in environment variables
• Input validation on all endpoints
• CORS configured for specific origins
• For production deployments, implement authentication, rate limiting, and HTTPS

License

This project is for educational purposes.

Acknowledgments

• MovieLens dataset provided by GroupLens Research
• Built with Flask, React, MongoDB, and scikit-learn