End-to-End Customer Churn Prediction System: Complete Implementation from Data Cleaning to Real-Time API

This project is an end-to-end machine learning engineering solution built on telecom industry customer data, covering SMOTE oversampling for class imbalance handling, multi-model comparison and selection, FastAPI real-time prediction service, and Tableau visualization analysis. It fully covers the entire process from data cleaning to production deployment, providing actionable technical references for enterprise customer churn prediction. The project is sourced from the customer-churn-prediction project maintained by fahad8-commits on GitHub, released in June 2026.

In industries like telecom, customer churn is a core challenge—acquiring new customers costs more than 5 times the cost of retaining existing ones. This project targets the telecom industry, using the Telco Customer Churn dataset with approximately 7000 records. The goal is binary classification to predict whether a customer will churn, with data covering dimensions such as demographics, service subscriptions, contract terms, and billing data.

Data Feature Classification:

• Demographic features: gender, age, spouse/dependent status
• Service usage features: phone/internet service type, subscription status of online security, etc.
• Contract and billing features: contract type, payment method, tenure, monthly/total charges

Core Challenges: Class imbalance (churned customers account for only 15%-20%). Without handling, the model will tend to predict the majority class, reducing the ability to identify churned customers.

ETL Data Pipeline: Implement an automated process for data loading, cleaning, feature preparation, and storage Feature Engineering: Handle missing values (e.g., blank Total Charges field), category encoding (one-hot/label encoding), feature scaling, and train-test split Class Imbalance Handling: Use SMOTE technology to generate synthetic minority class samples, balance training data to improve the model's ability to identify churned customers.

Train and compare multiple algorithms:

• Baseline model: Logistic Regression (high interpretability)
• Tree model family: Decision Tree (prone to overfitting), Random Forest (Bagging ensemble), XGBoost (gradient boosting, key optimization)

Evaluate using metrics such as accuracy, precision, recall, F1 score, and ROC-AUC, then select the model with the best performance on the validation set for deployment.

FastAPI Real-Time Prediction: Build a POST /predict endpoint that receives customer feature JSON and returns churn probability, run using Uvicorn, supporting local/cloud deployment Tableau Dashboard: Provide core metrics (total customers, churn rate, etc.) and multi-dimensional analysis (correlation between contract type, monthly consumption, tenure, and churn), helping business personnel gain data insights.

Achievements: Covers core MLOps links, solves class imbalance issues, implements model serviceization and visualization, providing complete engineering practice references for developers Future Directions: Plan to integrate AWS S3, Docker containerization, CI/CD pipelines, automatic model retraining, and Streamlit applications, evolving towards a complete MLOps system.