📡 Telecom Churn & Customer Retention Analytics Platform

An enterprise-grade customer intelligence and churn prediction system. This project implements an end-to-end Machine Learning pipeline that processes subscriber records, fits predictive classifiers (Logistic Regression, Random Forest, XGBoost), exposes a real-time scoring API, and presents insights via a dynamic Streamlit dashboard.

---

🏗️ System Architecture

flowchart TD
    subgraph Offline Pipeline [1. Offline Training & Pipeline]
        RawData[(Raw Data)] --> Loader[Data Loader]
        Loader --> Trans[Feature Transformers]
        Trans --> SMOTE[SMOTE Oversampler]
        SMOTE --> Tuning[Optuna Tuner]
        Tuning --> Train[Model Trainer]
        Train --> Eval[Model Evaluator]
        Eval --> Explainer[SHAP Explainer]
        Eval --> Register[Model Registry]
    end

    subgraph Serving [2. serving Layer]
        Register --> ServeAPI[FastAPI Service]
    end

    subgraph Client [3. Presentation Layer]
        ServeAPI --> Streamlit[Streamlit Dashboard]
        CSVUpload[CSV Batch Upload] --> Streamlit
    end

Loading

---

📁 Repository Structure

telecom-retention/
├── api/                    # FastAPI application (main.py, predictor.py, schemas.py)
├── config/                 # Central settings and hyperparameters (settings.py)
├── dashboard/              # Streamlit dashboard pages & visual components
├── data/                   # Local storage block (Git-ignored)
│   ├── raw/                # Raw subscriber records (.csv)
│   ├── processed/          # Feature matrices for model consumption (.csv)
│   └── outputs/            # Risk profiles, SHAP metrics, evaluation charts (.png, .csv)
├── docs/                   # System documentation & SRS text
│   └── architecture.txt    # Detailed Software Requirements Specification (SRS)
├── notebooks/              # Prototyping & EDA reports (generate_eda_report.py)
├── src/                    # Primary source code layer
│   ├── ingestion/          # Ingestion pipelines & validation checks
│   ├── features/           # Feature engineering custom OOP transformers
│   ├── models/             # Machine Learning estimators, evaluation, & SHAP
│   ├── pipelines/          # Training & Inference pipeline orchestration
│   ├── tracking/           # MLflow tracking integrations
│   └── registry/           # Local model version control and registry
├── tests/                  # Automated pytest validation suites
├── Dockerfile              # Docker blueprint for containerized environments
├── docker-compose.yml      # Orchestration for FastAPI & Streamlit services
├── generate_synthetic_data.py # Utility to create synthetic subscriber datasets
├── run_pipeline.py         # Entry-point CLI to run ingestion, training, & scoring
└── requirements.txt        # Python dependency manifest

---

🚀 Getting Started

1. Prerequisites

Ensure you have Python 3.10+ installed on your system.

2. Environment Setup

Clone the repository and set up a clean Python virtual environment:

# Create a virtual environment
python -m venv venv

# Activate the virtual environment
# On Windows (PowerShell):
venv\Scripts\Activate.ps1
# On macOS/Linux:
source venv/bin/activate

# Install all required package dependencies
pip install -r requirements.txt

3. Generate Synthetic Data

If you don't have subscriber data, generate a synthetic cohort of 10,000 subscribers:

python run_pipeline.py --generate-data --rows 10000 --seed 42

This saves raw subscriber records to data/raw/subscribers.csv.

4. Run the Training Pipeline

Train and evaluate models (Logistic Regression, Random Forest, and XGBoost), save metrics, generate evaluation curves, and compute SHAP feature importance:

python run_pipeline.py --mode train

Tip: Add --no-shap to skip SHAP analysis for faster execution, or --tune to run Optuna hyperparameter optimization before training.

5. Start the Services

Start the Churn Prediction API (FastAPI backend)

python -m uvicorn api.main:app --host 127.0.0.1 --port 8000 --reload

• Interactive API Docs (Swagger): http://127.0.0.1:8000/docs
• Alternative Docs (ReDoc): http://127.0.0.1:8000/redoc

Start the Streamlit Dashboard (Frontend)

In a new terminal window (with the virtual environment activated):

python -m streamlit run dashboard/app.py --server.port 8501 --server.address 127.0.0.1

• Dashboard Web UI: http://127.0.0.1:8501

---

📈 Model Performance Leaderboard

Trained on 10,000 synthetic subscriber records (using an 80/20 train-test split):

Model	Accuracy	AUC-ROC	Precision	Recall	F1-Score
Logistic Regression	70.55%	0.8002	0.4442	77.48%	0.5647
Random Forest	72.90%	0.7899	0.4656	67.34%	0.5506
XGBoost	74.05%	0.7608	0.4770	54.77%	0.5099

🏆 Best Performing Model: Logistic Regression based on highest AUC-ROC (0.8002) and Recall (77.48%).

---

🐳 Docker Deployment

You can orchestrate both services locally using Docker Compose:

# Build and run containers
docker-compose up --build

This launches the FastAPI service on port 8000 and the Streamlit Dashboard on port 8501.

---

🧪 Running Tests

Verify the code correctness and unit-test modules:

# Run all test suites
pytest