E-Commerce Recommendation System

A small recommendation-system laboratory built with FastAPI, SQLite, Python ML tooling, React, TypeScript, and Vite.

Looking to feature this project on your website or blog? Check out the SEO & GEO-optimized Portfolio Listing Guide.

The demo shows how recommendations are generated, not just which products are recommended. It includes popularity, category, content-based, collaborative, lightweight embedding-style similarity, and hybrid recommendation strategies with structured explanations.

What Is Included

• FastAPI backend with SQLAlchemy and SQLite
• uv project setup with a local virtual environment workflow
• Deterministic synthetic seed data: 240 products, 60 users, and several thousand interactions
• Product browser with event tracking
• User simulator with profile and recent activity
• Recommendation explorer with algorithm switching
• Hybrid weight sliders and diversity penalty
• Score breakdown drawer with component scores
• Model comparison page
• User-item and product-similarity matrix viewers
• Basic offline-style evaluation metrics
• Dockerfiles and docker-compose.yml

Screenshots

Here is a visual walkthrough of the laboratory dashboard and features:

1. Analytics Dashboard	2. User Profile Simulator

3. Product Event Logger	4. Strategy Recommendation Explorer

5. Hybrid Sliders Playground	6. Scoring Breakdown Drawer

7. Similarity Matrices	8. Model Comparison Metrics

Recommendation Methods

Content filtering compares product text features such as name, category, brand, description, and tags. Collaborative filtering uses the user-item interaction matrix and SVD to infer products a user may prefer. The hybrid recommender combines popularity, content, collaborative, and lightweight semantic similarity scores into one transparent ranking.

Backend Setup With uv

cd backend
uv venv
uv sync --extra dev
uv run uvicorn app.main:app --reload

The backend seeds SQLite automatically on startup.

Useful commands:

uv run pytest
uv run python -m app.ml.train --model content
uv run python -m app.ml.evaluate

Frontend Setup

cd frontend
npm install
npm run dev

Set VITE_API_URL if the backend is not running at http://localhost:8000.

Docker

docker compose up --build

Backend: http://localhost:8000

Frontend: http://localhost:5173

API Highlights

• GET /api/products
• GET /api/users/{user_id}/profile
• POST /api/events
• GET /api/recommendations/{user_id}?algorithm=hybrid
• POST /api/recommendations/{user_id}/hybrid
• GET /api/recommendations/{user_id}/compare
• GET /api/analytics/overview
• GET /api/analytics/model-performance

Production Migration Notes

The backend keeps recommendation logic outside API routes. SQLAlchemy makes SQLite replaceable with PostgreSQL. The in-memory feature builders can later be moved behind Redis, a feature store, a vector database, and scheduled training jobs without changing the React API contract.