E-Commerce Recommendation System (Python + React)

📖 Project Overview

Most recommendation systems operate as a "black box," outputting product suggestions without explaining why they were selected. This project acts as an interactive simulator and analyzer, stripping away the mystery.

Built with Python (FastAPI, Pandas, NumPy, scikit-learn) on the backend and React (TypeScript, Tailwind CSS, Recharts) on the frontend, it contains a pre-seeded synthetic database of 240 products, 60 active users, and thousands of real-time behavioral interaction events.

Users can simulate shopping behaviors (views, clicks, wishlist additions, cart adds, purchases) and watch recommendation models update dynamically in a visual playground.

🛠️ Key Features

1. Multi-Strategy Recommendation Engines

The backend implements six distinct recommendation strategies:

• Popularity-Based: Recommends globally trending items based on weighted interactions.
• Category Affinity: Recommends items matching categories the user has frequently interacted with.
• Content-Based Filtering: Utilizes TF-IDF and Cosine Similarity to analyze text metadata (product name, description, tags, brand).
• Collaborative Filtering: Uses Singular Value Decomposition (SVD) on the user-item interaction matrix to infer hidden user preferences.
• Item-to-Item Similarity: Suggests items that are mathematically closest to the user's recently purchased or viewed products.
• Hybrid Strategy: Combines popularity, content, collaborative, and semantic similarity scores using adjustable weighting and a diversity penalty.

2. Interactive Simulator & Playground

• User Behavior Simulator: Step into the shoes of any of the 60 pre-seeded users. View their active feeds, recent interaction histories, and real-time category/brand affinities.
• Real-time Event Injector: Click, view, or buy products to immediately send interaction events back to the backend database.
• Weight Tuning Sliders: Adjust weights for popularity, content, collaborative, and semantic similarity on the fly to see how the final hybrid list changes.
• Diversity Penalty: Apply penalties to similar items to force a wider, more diverse set of product recommendations.

3. Deep Analytical & Explanation Tools

• Score Breakdown Drawer: Click on any recommended product to inspect the mathematical breakdown of its ranking score.
• Matrix Viewers: Inspect the raw User-Item Interaction Matrix and the Product-Product Similarity Matrix.
• Offline Evaluation Metrics: Compute and analyze overall model precision, recall, and coverage.

🏗️ Technical Architecture

       [ React UI (Vite + TS) ]
                  |
        HTTP REST API Requests
                  v
     [ FastAPI Backend Service ]
         /                  \
   [ SQLite DB ]    [ ML Feature Builders ]
  (Pre-seeded data)    (scikit-learn / SVD)

The system separates recommendation logic from database queries, meaning the SQLite database can be easily swapped for PostgreSQL, and the in-memory feature builders can transition into a vector store (e.g., Qdrant, pgvector) or Redis in a production migration.

🚀 How to Run the Project

Option 1: Quick Start with Docker (Recommended)

Make sure you have Docker and Docker Compose installed, then run:

docker compose up --build

• Frontend Dashboard: http://localhost:5173
• FastAPI Backend (Swagger API Docs): http://localhost:8000/docs

Option 2: Local Development Setup

Backend Setup (Python + uv)

Ensure you have the uv package manager installed.

# Navigate to the backend directory
cd backend

# Create a virtual environment
uv venv

# Synchronize dependencies (including dev tools)
uv sync --extra dev

# Run the FastAPI server
uv run uvicorn app.main:app --reload

Note: The SQLite database seeds automatically on its first run.

Frontend Setup (React + Vite)

Ensure you have Node.js installed.

# Navigate to the frontend directory
cd frontend

# Install packages
npm install

# Run the development server
npm run dev

Q1: How is the interaction weight structured in the database?

To accurately model user behavior, interactions are stored in a database table where each event type has a specific weight representing interest level:

These weights are normalized to construct the user-item interaction matrix, serving as the basis for collaborative filtering.

Q2: What mathematical similarity is used for the content-based recommender?

Text metadata (name, description, tags, brand, category) is compiled into a single document string for each product. TF-IDF vectorization converts these documents into numerical matrices. The cosine similarity between these vector matrices calculates how closely related two items are:

$$\text{Cosine Similarity}(A, B) = \frac{A \cdot B}{|A| |B|}$$

Q3: How does the SVD model handle sparse interaction matrices?

In collaborative filtering, SVD (Singular Value Decomposition) factorizes the sparse user-item interaction matrix into lower-dimensional dense matrices, capturing latent factor vectors for both users and products. In this laboratory, scikit-learn's TruncatedSVD is used to approximate ratings for items the user has not yet interacted with, filling matrix gaps.