Siddharth69/supermarket-segmentation

Supermarket Customer Segmentation App

Full-stack ML web application that clusters supermarket customers into behavioral segments using RFM analysis, KMeans clustering, and SHAP explainability, visualized through a premium React dashboard.

Architecture

graph LR
    subgraph Frontend ["Frontend (Vite + React)"]
        A[App.jsx] --> B[UploadPanel]
        A --> C[SegmentCards]
        A --> D[ScatterPlot]
        A --> E[ShapChart]
        A --> F[CustomerTable]
    end
    subgraph Backend ["Backend (FastAPI)"]
        G[main.py] --> H[segmentation.py]
        G --> I[generate_data.py]
        H --> J[KMeans + SHAP]
    end
    Frontend -->|REST API| Backend
    Backend -->|CSV/XLSX| K[(uploads/)]

Prerequisites

• —Python 3.10+
• —Node.js 18+

Setup & Running

Backend Setup

1. 1.Open terminal and navigate to the backend folder.
2. 2.Install dependencies:

   pip install -r requirements.txt

1. 1.Run the FastAPI server:

   uvicorn main:app --reload --port 8000

Frontend Setup

1. 1.Open terminal and navigate to the frontend folder.
2. 2.Install dependencies:

   npm install

1. 1.Start the dev server:

   npm run dev

API Endpoint Reference

Custom CSV Format

Upload custom data via the UI. Ensure the file is .csv and has the following exact columns:

• —customer_id (string)
• —purchase_date (YYYY-MM-DD or parsable date string)
• —transaction_value (numeric)