MasaCart

MasaCart is a full-stack e-commerce platform built to explore modern recommendation system techniques used by large online marketplaces.

It combines traditional shopping workflows with machine learning-driven personalization so users can browse products, manage carts, place orders, and receive smarter recommendations based on behavior and product semantics.

Project Goals

• Build an end-to-end shopping platform with production-style architecture.
• Track user interactions (views, cart actions, purchases) as recommendation signals.
• Use vector embeddings to power semantic search and recommendation workflows.
• Generate user profile embeddings from interaction history for personalized discovery.

Core Shopping Features

• User authentication with JWT (register, login, token refresh).
• Product catalog browsing and product detail pages.
• Product reviews and rating summaries on product.
• Product metadata with category and brand relationships.
• Cart operations (add, remove, update quantity).
• Checkout flow and order history.

Recommendation and Search Features

• Semantic product search using vector embeddings (pgvector + cosine similarity).
• Similar product recommendations from product content embeddings.
• User behavior tracking endpoints for:
  • Product views
  • Cart events
  • Purchases (through order items)
• User profile embeddings generated from weighted interaction history.
• Personalized homepage recommendations for authenticated users.

Tech Stack

• Backend: Django, Django REST Framework, PostgreSQL, pgvector, SimpleJWT
• Frontend: React, Vite, TypeScript, Tailwind CSS
• ML/Embeddings: sentence-transformers (default model: BAAI/bge-small-en-v1.5)

Repository Structure

• backend/: Django project and domain apps
  • users/: auth and profile endpoints
  • products/: catalog, import, embeddings
  • orders/: cart and order workflows
  • interactions/: behavioral tracking events
  • recommendations/: semantic search and personalized recommendations
• frontend/: React + Vite client app
  • pages/, components/, context/, api/, types/

Prerequisites

• Python 3.10+
• Node.js 18+
• PostgreSQL with pgvector extension enabled

Backend Setup

1. Create a virtual environment and install Python dependencies:

python -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt

2. Configure environment variables (example):

export SECRET_KEY="your_django_secret"
export DB_NAME="masacart"
export DB_USER="postgres"
export DB_PASSWORD="postgres"
export DB_HOST="127.0.0.1"
export DB_PORT="5432"
export FRONTEND_URL="http://localhost:5173"

3. Enable pgvector in PostgreSQL:

CREATE EXTENSION IF NOT EXISTS vector;

4. Run migrations and start Django:

cd backend
python manage.py migrate
python manage.py runserver

Backend default URL: http://127.0.0.1:8000

Frontend Setup

1. Install dependencies and start Vite:

cd frontend
npm install
npm run dev

2. Set frontend environment variable (for API base URL), for example in frontend/.env:

VITE_DJANGO_BASE_URL=http://127.0.0.1:8000

Frontend default URL: http://localhost:5173

Data and Embedding Pipeline

From backend/:

1. Import products (DummyJSON source):

python manage.py import_products

2. Generate embeddings for all products:

python manage.py generate_embeddings

This populates the product embedding field used for semantic search, related product suggestions, and user personalization.

API Overview

• Users: /api/users/
  • register, login, refresh, profile
• Products: /api/products/
  • listing, details
• Product reviews: /api/products//reviews/
• Product-to-product recommendations: /api/products//recommendations/
• Semantic search: /api/products/search/?q=
• Interactions: /api/interactions/
  • track-view/
  • track-cart/
• Personalized homepage recommendations: /api/recommendations/homepage/
• Orders and cart: /api/orders/

Key Recommendation Flow

1. Product embeddings are generated from title + category + brand + description.
2. User interactions are collected from views, cart events, and purchases.
3. A weighted user embedding is computed:
   • views: weight 1
   • cart events: weight 3
   • purchases: weight 5
4. Products are ranked by vector similarity against the user embedding.

Testing

• Backend tests:

cd backend
python manage.py test

• Frontend lint:

cd frontend
npm run lint

Notes

• Recommendation quality depends on interaction volume and embedding quality.
• First-time users may have limited personalization until enough behavior is tracked.
• Embedding generation requires internet access on first run to download model weights.