Customer Segmentation & Retention Analytics Platform

Enterprise-grade Customer Segmentation, Churn Prediction & Retention Analytics Platform.

Overview

An interesting production-ready data science application demonstrating end-to-end data engineering, machine learning, backend development, and dashboard capabilities.

Features

• ETL Pipeline: Extract, validate, clean, transform, and load retail data into normalized schema
• SQL Analytics: Revenue analysis, customer insights, product performance, KPIs
• Feature Engineering: RFM analysis, behavioral features, geographic features
• Customer Segmentation: KMeans clustering with automatic optimal-k selection
• Churn Prediction: XGBoost classifier with feature importance analysis
• Recommendation Engine: Item-based collaborative filtering (cosine similarity)
• REST API: FastAPI with endpoints for analytics, ML predictions, and recommendations
• Dashboard: Streamlit-powered interactive analytics dashboard
• Testing: 28 pytest tests covering database, analytics, ML, and API
• Docker: Full containerized deployment with PostgreSQL

Tech Stack

Layer	Technology
Language	Python 3.14
Data Processing	Pandas, NumPy
Machine Learning	Scikit-learn, XGBoost
Database	PostgreSQL 17 / SQLite (local dev)
ORM	SQLAlchemy 2.x
Migrations	Alembic
API	FastAPI
Dashboard	Streamlit
Visualization	Plotly
Validation	Pydantic
Containerization	Docker
Testing	Pytest

Project Structure

customer-segmentation-platform/
├── app/
│   ├── api/              # FastAPI endpoints & schemas
│   ├── analytics/        # SQL analytics queries
│   ├── config/           # Application configuration (Pydantic Settings)
│   ├── core/             # Logging, exceptions
│   ├── dashboard/        # Streamlit dashboard app
│   ├── database/         # SQLAlchemy setup, ORM models, connection
│   ├── etl/              # Extract, Transform, Load pipelines
│   └── ml/               # Feature engineering, segmentation, churn, recommendations
├── alembic/              # Database migrations
├── data/
│   ├── raw/              # Raw data files
│   ├── processed/        # Cleaned data
│   └── features/         # Engineered feature CSVs
├── models/               # Trained ML model artifacts (.joblib, .json)
├── reports/              # Generated analytics reports
├── tests/                # Test suite (28 tests)
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
└── .env.example

Quick Start

Prerequisites

• Python 3.14
• PostgreSQL 17 (or use SQLite locally)
• Git

Installation

1. Clone the repository:

git clone <repository-url>
cd customer-segmentation-platform

2. Create virtual environment:

python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/Mac
source .venv/bin/activate

3. Install dependencies:

pip install -r requirements.txt

4. Configure environment:

copy .env.example .env
# Edit .env with your database credentials
# For local SQLite, set: DATABASE_URL_OVERRIDE=sqlite:///path/to/database.db

Running the Full Pipeline

Step 1: Generate Sample Data

python -m app.etl.generate_sample

Step 2: Run Full ETL Pipeline

python -m app.etl.run_etl

Step 3: Run Analytics Reports

python -m app.analytics.run_analytics

Step 4: Train ML Models

python -m app.ml.features        # Build feature matrix
python -m app.ml.segmentation    # Train segmentation model
python -m app.ml.churn           # Train churn prediction model
python -m app.ml.recommendations # Build recommendation engine

Step 5: Start API Server

uvicorn app.api.main:app --reload --host 0.0.0.0 --port 8000

Step 6: Start Dashboard

streamlit run app/dashboard/app.py

Docker Deployment

docker-compose up --build

This starts:

• PostgreSQL on port 5432
• FastAPI on port 8000
• Streamlit on port 8501

Testing

pytest tests/ -v

API Endpoints

Method	Endpoint	Description
GET	/health	Health check
GET	/api/v1/kpi	KPI summary
GET	/api/v1/analytics/top-customers	Top customers by revenue
GET	/api/v1/analytics/revenue-by-country	Revenue by country
GET	/api/v1/analytics/monthly-revenue	Monthly revenue trends
GET	/api/v1/analytics/product-performance	Product rankings
GET	/api/v1/ml/segments	Customer segments
GET	/api/v1/ml/churn	Churn predictions
GET	/api/v1/ml/recommendations/{customer_id}	Product recommendations

Database Schema

Table	Description	Key Columns
customers	Customer dimension	customer_id (PK), country
products	Product dimension	stock_code (PK), description
orders	Order/invoice fact	invoice (PK), customer_id (FK), invoice_date
order_items	Line item fact	id (PK), invoice (FK), stock_code (FK), quantity, price, line_total

ML Models

Model	Algorithm	Purpose	Artifact
Segmentation	KMeans	Customer clustering	segmentation_model.joblib
Churn	XGBoost	Churn prediction	churn_model.joblib
Recommendations	Cosine Similarity	Product recommendations	item_similarity.joblib

License

This project is for educational and portfolio purposes.