Full Stack Machine Learning Recommendation System

A complete ML movie recommendation system with React frontend and FastAPI backend
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. System Architecture
3. Getting Started
   • Prerequisites
   • Installation
4. Project Structure
5. Usage
6. License
7. Contact

About The Project

This project is a full-stack Machine Learning movie recommendation system featuring:

• React-based frontend with responsive UI
• FastAPI backend with GRU4Rec recommendation model
• User authentication and rating system
• Admin interface for content management
• Scheduled model retraining with Celery

The system provides personalized movie recommendations based on user ratings and behavior with the help of machine learning model.

(back to top)

Built With

• 
• 
• 
• 
• 

(back to top)

System Architecture

The architecture diagram above illustrates the main components of the recommendation system:

1. Frontend: React-based user interface
2. Backend: FastAPI server handling requests
3. Database: PostgreSQL for data persistence
4. Recommendation Engine: GRU4Rec model for personalized recommendations
5. Celery Worker: Background tasks for model training
6. Redis: Message broker for task queue

(back to top)

video_demo_rec_system.webm

Getting Started

To get a local copy up and running follow these simple steps.

Prerequisites

• Docker and Docker Compose
• Node.js (for frontend development)
• Python 3.8+ (for backend development)

Installation

1. Clone the repo

   git clone https://github.com/george-mountain/full-stack-recommendation-system.git

2. Copy environment file

   cp .env.example .env

3. Start the backend API container

   docker compose up --build

4. Populate the database with movie data

   docker compose exec app python /app/scripts/seed_db.py

5. Navigate to frontend and install dependencies

   cd recommendation-frontend/
   npm install
   npm run dev

(back to top)

Project Structure

Backend API Structure

.
├── app/
│   ├── __init__.py
│   ├── main.py                 # FastAPI app, routers
│   ├── core/
│   │   ├── __init__.py
│   │   └── config.py           # Settings and configurations
│   ├── db/
│   │   ├── __init__.py
│   │   ├── base_class.py       # Base for SQLAlchemy models
│   │   ├── models.py           # SQLAlchemy ORM models (User, Movie, Rating)
│   │   ├── session.py          # Async database session setup
│   │   └── crud.py             # CRUD operations
│   ├── schemas/
│   │   ├── __init__.py
│   │   ├── movie.py            # Pydantic schemas for movies
│   │   ├── rating.py           # Pydantic schemas for ratings
│   │   ├── user.py             # Pydantic schemas for users
│   │   └── token.py            # Pydantic schemas for JWT tokens
│   ├── api/
│   │   ├── __init__.py
│   │   ├── deps.py             # Dependencies (e.g., get_db, get_current_user)
│   │   └── v1/
│   │       ├── __init__.py
│   │       ├── api.py          # API router aggregation
│   │       └── endpoints/
│   │           ├── __init__.py
│   │           ├── users.py
│   │           ├── movies.py
│   │           ├── ratings.py
│   │           └── recommendations.py
│   ├── services/
│   │   ├── __init__.py
│   │   └── recommender/
│   │       ├── __init__.py
│   │       ├── model.py        # GRU4Rec Keras model definition
│   │       ├── predict.py      # Prediction logic
│   │       ├── preprocessing.py # Data preprocessing for training/prediction
│   │       └── train.py        # Training script for the model
│   ├── worker/
│   │   ├── __init__.py
│   │   ├── celery_app.py       # Celery app instance and beat schedule
│   │   └── tasks.py            # Celery tasks (e.g., model training)
│   └── security.py             # Password hashing and JWT utilities
├── data/                         # To store movielens raw data (optional, for initial seeding)
│   └── ml-1m/                    # Extracted movielens data (if downloaded)
├── models_store/                 # To save trained Keras models
│   └── gru4rec_model.keras       # Example saved model
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── .env_example                  # Example environment variables

Frontend Structure

recommendation-frontend/
├── node_modules/
├── public/
└── src/
    ├── assets/
    ├── components/
    │   ├── Admin/
    │   │   └── AdminPage.jsx
    │   ├── Auth/
    │   │   └── AuthForm.jsx
    │   ├── Common/
    │   │   ├── DisplayAverageRating.jsx
    │   │   ├── LoadingSpinner.jsx
    │   │   ├── MessageBox.jsx
    │   │   ├── MovieCard.jsx
    │   │   ├── RatingModal.jsx
    │   │   └── StarRatingInput.jsx
    │   └── Icons/
    │       ├── ArrowLeftIcon.jsx
    │       ├── FilmIcon.jsx
    │       ├── FilterIcon.jsx
    │       ├── HomeIcon.jsx
    │       ├── LockIcon.jsx
    │       ├── LogOutIcon.jsx
    │       ├── MenuIcon.jsx
    │       ├── SearchIcon.jsx
    │       ├── SettingsIcon.jsx
    │       ├── StarIcon.jsx
    │       ├── ThumbsUpIcon.jsx
    │       ├── TrashIcon.jsx
    │       ├── UploadCloudIcon.jsx
    │       ├── UserIcon.jsx
    │       └── XIcon.jsx
    ├── contexts/
    │   ├── AppContext.jsx
    │   └── AuthContext.jsx
    ├── Layout/
    │   ├── Footer.jsx
    │   └── Navbar.jsx
    └── pages/
    |   ├── HomePage.jsx
    |   └── MovieDetailPage.jsx
    └── services/
    |    ├── ApiService.js
    |   
    |
    └── styles/
        ├── index.css

(back to top)

Usage

After installation, access the services via:

• Backend API docs: http://127.0.0.1:8000/docs
• Frontend: http://localhost:5173/
• PGAdmin: http://localhost:5050/ (credentials: admin@admin.com / admin1234)

Admin Access:

1. Register with email: admin@example.com
2. Login and access the admin page
3. Manage movies and retrain the recommendation model

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Project Link: https://github.com/george-mountain/full-stack-recommendation-system

(back to top)