🛒 E-Commerce Product Classifier

A production-grade NLP system that classifies product listings into 19 categories using fine-tuned DistilBERT — with real-time data drift detection, automated monitoring, and an interactive React analytics dashboard. Built the way ML systems actually run in production.

---

The Problem This Solves

E-commerce platforms with millions of SKUs rely on accurate product categorization for search ranking, recommendations, and inventory management. Manual tagging doesn't scale. A misclassified product is effectively invisible to buyers searching the right category.

This system automates product classification at inference speeds of ~42ms per request — and crucially, detects when incoming product data starts drifting from the training distribution before accuracy silently degrades in production.

---

📊 Model Performance

Fine-tuned on 50,000 Amazon product samples across 19 categories.

Metric	Score
Accuracy	68.3%
F1 Score (Macro)	0.641
Precision (Macro)	0.643
Recall (Macro)	0.683

Context: Macro F1 of 0.641 across 19 heavily imbalanced categories is the honest aggregate. The model excels in high-signal categories and struggles in semantically overlapping ones — a known challenge in multi-class product taxonomy. See per-category breakdown below.

Top-Performing Categories:

Category	F1 Score
🎵 Digital Music	97.2%
👗 Amazon Fashion	85.8%
🎸 Musical Instruments	84.5%
🚗 Automotive	84.1%

Hardest Categories (semantically overlapping):

These categories share vocabulary (e.g., "Electronics" vs "Computers", "Toys" vs "Baby Products") — a known challenge in flat multi-class taxonomies that hierarchical classification would address.

---

🏗️ System Architecture

                        ┌─────────┐
                        │  User   │
                        └────┬────┘
                             │ HTTP POST
                             ▼
                   ┌──────────────────┐
                   │  FastAPI Backend  │
                   └────────┬─────────┘
                  Inference │         │ Log
                            │         │
                    ┌───────▼──┐   ┌──▼──────────────────┐
                    │DistilBERT│   │ SQLite Predictions DB │
                    │Classifier│   └──────────┬────────────┘
                    └───┬──────┘              │ Metrics
                   Sync │                     ▼
                        │         ┌───────────────────────┐
                        │         │   Performance Tracker  │
                        ▼         └───────────┬────────────┘
          ┌─────────────────────────┐         │ Real-time Data
          │ Evidently AI            │         │
          │ Drift Detector          │         │
          └────────────┬────────────┘         │
                Report │                      │
                        ▼                    ▼
                   ┌────────────────────────────┐
                   │       React Dashboard       │
                   └────────────────────────────┘

Flow:

1. Product listing hits the FastAPI endpoint
2. DistilBERT classifier runs inference (~42ms)
3. Prediction + metadata logged to SQLite
4. Evidently AI monitors incoming text distribution via PSI
5. Performance Tracker computes rolling accuracy metrics
6. React Dashboard visualizes everything in real time

---

✨ Features

🛠️ Backend (FastAPI)

• Async inference — single and batch prediction endpoints
• Pydantic v2 validation — strict input/output schema enforcement
• Automated logging — every request logged with latency, confidence score, and prediction

📈 Monitoring & Observability

• Data drift detection — Evidently AI monitors text distribution shifts using Population Stability Index (PSI)
• Performance tracking — SQLite-backed persistent logging with rolling metric calculations
• A/B testing infrastructure — Chi-square framework for comparing model versions before promoting to production

💻 React Analytics Dashboard

• Real-time accuracy trends and confidence distribution charts
• Inference latency monitoring
• Interactive model playground for live predictions
• Drift status indicators and system health view
• Per-category performance breakdown

---

🚀 Quick Start

Prerequisites

• Python 3.11+
• Node.js 20+
• Docker (optional)

1. Clone the repository

git clone https://github.com/Emart29/ecommerce-product-classifier.git
cd ecommerce-product-classifier

2. Set up the Python environment

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

3. Initialize data directories

mkdir -p data/monitoring/drift_reports

4. Start the API server

python -m src.api.main

API live at http://localhost:8000 · Swagger UI at /docs

5. Start the React dashboard

cd frontend
npm install
npm run dev

Dashboard live at http://localhost:5173

Docker (one command)

docker-compose up --build

---

📡 API Reference

POST /predict — Classify a single product

Request:

{
  "title": "Acoustic Guitar Starter Pack with Tuner and Bag"
}

Response:

{
  "category": "Musical Instruments",
  "confidence": 0.921,
  "latency_ms": 42.3
}

POST /predict/batch — Classify multiple products

Accepts an array of product objects. Full interactive docs at /docs.

---

🧪 Running Tests

# Full test suite
PYTHONPATH=. pytest tests/ -v

# Monitoring-specific tests
PYTHONPATH=. pytest tests/test_monitoring.py -v

---

📁 Project Structure

ecommerce-product-classifier/
├── src/
│   └── api/                    # FastAPI routes, schemas, inference
├── frontend/                   # React analytics dashboard
├── models/                     # Fine-tuned DistilBERT weights & config
├── data/
│   └── monitoring/
│       └── drift_reports/      # Evidently AI HTML drift reports
├── scripts/                    # Data generation & evaluation utilities
├── tests/                      # Pytest test suite
├── .github/workflows/          # CI/CD pipeline (lint → test → Docker build)
├── docker-compose.yml
├── Dockerfile
├── params.yaml                 # Configurable model & training params
└── requirements.txt

---

🛠️ Tech Stack

Layer	Technologies
ML / NLP	PyTorch, HuggingFace Transformers, DistilBERT, Scikit-learn
Monitoring	Evidently AI (PSI drift detection)
Backend	FastAPI, Uvicorn, SQLAlchemy, Pydantic v2
Frontend	React (Vite), Tailwind CSS v4, Chart.js, Lucide Icons
DevOps	Docker, Docker Compose, Pytest, GitHub Actions

---

🔄 CI/CD Pipeline

Every push triggers an automated pipeline:

Push / PR → Lint (black + flake8) → Tests (pytest) → Docker Build

The pipeline enforces code quality and validates the container builds correctly before any merge — the same pattern used in production ML systems.

---

📌 Key Engineering Decisions

Why DistilBERT over a larger model? DistilBERT is 40% smaller and 60% faster than BERT-base with 97% of the performance. For a classification API serving real-time requests, latency matters more than marginal accuracy gains.

Why Evidently AI for drift detection? Most ML systems degrade silently — accuracy drops weeks before anyone notices. PSI-based drift detection catches distribution shifts early, giving teams time to retrain before users are impacted.

Why SQLite for monitoring logs? For a single-instance deployment, SQLite is zero-infrastructure, fast enough for rolling metrics, and trivially replaceable with PostgreSQL when scaling horizontally.

---

🗺️ Roadmap

• Hierarchical classification to resolve overlapping categories
• Model versioning with automatic promotion/rollback
• Streaming predictions for large batch jobs
• PostgreSQL migration for multi-instance deployment
• Alerting (Slack/email) on drift threshold breach

---

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for guidelines on branch naming, code style, commit conventions, and the PR process.

---

📄 License

Distributed under the MIT License. See LICENSE for details.

---

Built by Emmanuel Nwanguma
LinkedIn · GitHub · Email