Churn Prediction System
What This Project Shows
Scalable tabular preprocessing using
scikit-learntransformers (StandardScaler,LabelEncoder,SimpleImputer).Production-grade backend infrastructure powered by FastAPI and SQLite (via SQLAlchemy ORM).
Real-time model inference delivering risk categorizations (
High,Medium,Low) and numerical churn probabilities.Model performance validation (ROC-AUC: 94.9%, Recall: 96.6%) paired with feature importance breakdown for business explainability.
Interactive front-end portfolio dashboard built using HTML5, Tailwind CSS, and Chart.js.
Dataset and Features
Source: Kaggle dataset (505,000 total records).
Split: Stratified 80/20 train/test split (404K train / 101K test records).
Target Variable:
churn(Binary:0= retained,1= churned).Class Balance: Naturally balanced (55.5% churn rate, ratio 1.25). Handled with
class_weight='balanced'inside the estimator.
Preprocessing & Feature Schema:
7 Numerical Features:
tenure_months,monthly_charges,total_charges,support_tickets_last_3mo,avg_session_duration_min,login_frequency_weekly,nps_score.2 Categorical Features:
contract_type,payment_method.Missing values handled via
SimpleImputer, continuous variables normalized withStandardScaler, and categorical features encoded usingLabelEncoder.
Models and Performance
The primary architecture utilizes a single tuned RandomForestClassifier (100 estimators, max depth 10, min samples split 10, min samples leaf 5) trained on the 80/20 stratified split.
Evaluation Metrics (Held-out Test Set — 101K Records)
Model | Accuracy | Precision | Recall | F1 Score | ROC-AUC |
|---|---|---|---|---|---|
RandomForestClassifier | 0.9208 | 0.8989 | 0.9659 | 0.9312 | 0.9490 |
Notes on Model Results (Interpretation)
These results are strong for a single-model, production-minded baseline. Read in business terms:
ROC-AUC ≈ 0.95 — The model is excellent at ranking a high-risk customer above a low-risk one. Even without a fixed threshold, its ordering of risk is highly reliable.
Recall 96.6% — It catches ~97% of customers who actually churn. In retention, missing a churner (a false negative) is the costliest error, so this high recall is the correct bias.
Precision 89.9% — When the model flags a customer as "will churn," it is right about 9 times out of 10, so outreach teams are not wasting effort on false alarms.
F1 0.931 — A healthy balance between precision and recall; neither is being sacrificed for the other.
Accuracy 92.1% — Overall correctness is high, though for churn the recall/precision pair matters more than raw accuracy given business costs.
note: The single biggest predictor isn't price — it's whether the customer has had to open support tickets lately. That is an operational, fixable insight: smoothing the support experience may be the fastest lever for reducing churn.
Analysis Visualizations
1. Churn Distribution — class balance of the target (churn).
https://raw.githubusercontent.com/AsharArmoghan/ChurnPrediction/master/assets/churn_dist.png
2. Numerical Feature Distributions — spread/skew of the 7 numeric features.
https://raw.githubusercontent.com/AsharArmoghan/ChurnPrediction/master/assets/numerical_feature.png
3. Feature Distributions by Churn — how each feature differs between retained vs. churned customers.
4. Correlation Matrix — pairwise correlations among numeric features (multicollinearity check).
https://raw.githubusercontent.com/AsharArmoghan/ChurnPrediction/master/assets/correlation_matrix.png
5. Feature Importance (Random Forest) — horizontal bars ranking the drivers above.
https://raw.githubusercontent.com/AsharArmoghan/ChurnPrediction/master/assets/feature_importance.png
6. ROC Curve — visualizes the 0.949 AUC.
https://raw.githubusercontent.com/AsharArmoghan/ChurnPrediction/master/assets/roc_curve.png
7. Confusion Matrix — breakdown of true/false positives and negatives on the test set.
https://raw.githubusercontent.com/AsharArmoghan/ChurnPrediction/master/assets/confusion_matrix.png
Risk Business Thresholds:
High Risk: 70% or higher churn probability
Medium Risk: 40% to 69% churn probability
Low Risk: Less than 40% churn probability
Repository Structure
churnForecasting/
├── requirements.txt # Dependency list
├── .gitignore # Excludes artifacts, caches, DB, logs
│
├── advanced_pipeline/ # Minimal data utilities
│ ├── __init__.py # Exports load_kaggle_full, get_logger
│ ├── kaggle_data.py # Kaggle dataset loader (churn-only)
│ └── utils.py # Logging utilities
│
├── simple_churn_model.py # Standalone Random Forest model
├── models.py # SQLAlchemy ORM: Customer table
├── database.py # Engine / Session / Base / init_db / get_db
├── seed.py # Seed 100 sample customers into SQLite
├── main.py # FastAPI app + REST endpoints
├── index.html # Tailwind + Chart.js dashboard
│
├── notebooks/ # Jupyter notebooks
│ ├── 00_exploratory_data_analysis.ipynb # EDA on Kaggle data
│ └── 01_modeling.ipynb # Model training & evaluation
│
├── models/ # Trained model artifacts
│ └── simple_churn_model.pkl # Random Forest (14.6 MB)
│
├── database.db # SQLite file (created at runtime)
Architecture Notes
Class Imbalance
Dataset is naturally balanced (55.5% churn rate, ratio 1.25). Model uses class_weight='balanced' in RandomForestClassifier which automatically adjusts weights:
Class 0 (retained): weight ≈ 1.12
Class 1 (churned): weight ≈ 0.90
SMOTE is not required but available in
imbalanced-learnif needed.
Dependencies
Key packages (see requirements.txt):
scikit-learn>=1.9.0pandas>=3.0.0numpy>=2.5.0fastapi>=0.141.0,uvicorn>=0.52.0sqlalchemy>=2.0.0kagglehub>=1.0.0imbalanced-learn>=0.14.0
Optional (for notebooks):
jupyter,nbformat,nbconvert,ipykernel
cURL Terminal Examples
Fetch all customers
curl http://127.0.0.1:8000/api/customers
Run real-time prediction
curl http://127.0.0.1:8000/api/predict/churn/CUST0001
Retrieve portfolio breakdown
curl http://127.0.0.1:8000/api/dashboard-summary