ChurnPulse: Predictive Customer Churn Analytics Platform

ChurnPulse is a full-stack, enterprise-grade predictive analytics platform engineered to identify customer churn risks, analyze retention patterns, and deliver custom playbooks for customer success teams.

The platform utilizes a machine learning classifier (XGBoost) integrated with a FastAPI backend server, an SQLite database for history audits, and a premium cream-and-brown React single-page application enhanced with interactive charts.

---

📸 Platform Showcases

1. Landing Platform Page

A modern, dark-contrast landing interface designed with smooth layouts and glassmorphic headers.

2. Prediction Workspace & Scoring Analysis

Input controls mapped into tabs (Demographics, Services, and Billing) with range sliders, switch selectors, circular risk scoring gauges, and custom retention playbooks.

3. Animated Recharts Analytics

Interactive area, bar, and pie charts providing summaries of churn timelines, contract profiling distribution, internet lines, and payment channels.

4. Database Audit Registry

A responsive logs database table featuring text filtering, paged results, sorting, and custom deletion overlays.

---

🎯 Purpose of the Project

In telecom and utility subscriptions, customer acquisition costs (CAC) are significantly higher than retention costs. ChurnPulse empowers retention managers by:

1. Targeting Churn Risks: Computing probability indices using XGBoost to identify at-risk accounts before they cancel.
2. Diagnosing Retention Bottlenecks: Revealing key correlations (e.g. Month-to-month contracts and high billing rates) via interactive charts.
3. Triggering Actionable Playbooks: Recommending target offerings (e.g. contract term adjustments or loyalty check-ins) based on individual customer data profiles.

---

🛠 Tech Stack

• Machine Learning: Python, XGBoost, Scikit-learn, Pandas, Joblib
• Backend Framework: FastAPI (Uvicorn server), Pydantic (data schemas)
• Database & ORM: SQLite, SQLAlchemy ORM
• Frontend Library: React (JS), Vite build tool
• Styling & UI: Vanilla CSS Design Tokens (warm cream & cocoa brown palette)
• Animations & Icons: Framer Motion, Lucide React
• Visualizations: Recharts Components
• Containerization: Docker, Docker Compose

---

📂 Project Structure

customerchurns/
├── backend/                  # FastAPI Backend Service
│   ├── app/
│   │   ├── database.py       # SQLAlchemy engine & SQLite path
│   │   ├── main.py           # FastAPI routes & endpoints
│   │   ├── ml_service.py     # XGBoost preprocessing & scoring class
│   │   ├── models.py         # DB model mapping predictions
│   │   └── schemas.py        # Pydantic schemas validating API calls
│   ├── data/
│   │   └── churn_history.db  # Persistent SQLite database file
│   ├── models/
│   │   ├── xgboost_model.joblib  # Trained XGBoost binary model
│   │   ├── scaler.joblib         # Numeric scaler artifact
│   │   └── ui_metadata.json      # Dynamic validation bounds & mappings
│   ├── train.py              # ML training pipeline script
│   ├── requirements.txt      # Python libraries dependencies
│   └── Dockerfile            # Backend Python Docker image
│
├── frontend/                 # React Frontend Client
│   ├── src/
│   │   ├── components/       # Custom React subcomponents
│   │   │   ├── ConfirmModal.jsx  # Deletion overlay popup
│   │   │   ├── Dashboard.jsx     # Recharts visual panels
│   │   │   ├── Form.jsx          # Demographics, Services tabs form
│   │   │   ├── Hero.jsx          # CSS-mesh header hero landing
│   │   │   ├── History.jsx       # Paged logs registry table
│   │   │   ├── Results.jsx       # Risk percentage gauge & playbook
│   │   │   ├── StatsGrid.jsx     # Card metric summaries
│   │   │   └── Toast.jsx         # Custom overlay notifications
│   │   ├── App.jsx           # App state coordinator
│   │   ├── index.css         # Design system & CSS custom variables
│   │   └── main.jsx          # Vite React mounting
│   ├── package.json          # Node dependencies
│   └── Dockerfile            # Frontend Node Docker image
│
├── data/
│   └── WA_Fn-UseC_-Telco-Customer-Churn.csv  # Raw Telco Churn CSV
├── images/                   # Copied screenshots for README rendering
└── docker-compose.yml        # Orchestration layer for multi-containers

---

🚀 How to Run the Platform

Method 1: Docker Compose (Recommended)

This spins up the entire backend and frontend in isolated container networks without needing local dependencies.

1. Ensure Docker Desktop is running.
2. In the project root directory, run:

   docker-compose up --build

3. Access the interfaces:
   • Frontend Application: http://localhost:5173/
   • FastAPI Backend Swagger docs: http://localhost:8005/docs

---

Method 2: Manual Local Installation

1. Backend Server Setup

1. Navigate to the backend/ folder:

   cd backend

2. Create and activate a Python virtual environment:

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

3. Install dependencies:

   pip install -r requirements.txt

4. Train the ML Model (generates model binary files under models/):

   python train.py

5. Launch the backend API server:

   uvicorn app.main:app --host 127.0.0.1 --port 8005

2. Frontend Client Setup

1. Open a new terminal window and navigate to the frontend/ folder:

   cd frontend

2. Install Node dependencies:

   npm install --legacy-peer-deps

3. Run the Vite development server:

   npm run dev

4. Open your browser to: http://127.0.0.1:5173/