# akshayetukuri/customer-churn-predictor architecture

> Architecture diagram of the GitHub repository akshayetukuri/customer-churn-predictor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akshayetukuri/customer-churn-predictor
- Repository: https://github.com/akshayetukuri/customer-churn-predictor

## Overview

This is a telecom customer-churn prediction dashboard backed by a trained XGBoost model. The primary workflow is customer profile entry, feature preparation and scaling, churn-risk inference, and a SHAP explanation. The README also describes a notebook-based data and model-development workflow. The notebook’s individual implementation details were not sampled, so those stages and their sequence are included only as documented.

Main entry points: [`app.py`](https://github.com/akshayetukuri/customer-churn-predictor/blob/main/app.py) (Streamlit dashboard), [`xgb_model.pkl`](https://github.com/akshayetukuri/customer-churn-predictor/blob/main/xgb_model.pkl) (XGBoost model), [`archive/Telco_customer_churn.xlsx`](https://github.com/akshayetukuri/customer-churn-predictor/blob/main/archive/Telco_customer_churn.xlsx) (Customer dataset), [`churn_prediction.ipynb`](https://github.com/akshayetukuri/customer-churn-predictor/blob/main/churn_prediction.ipynb) (EDA and modeling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_development["Data and modeling"]
  node_raw_data["Customer dataset"]
  node_notebook["EDA and modeling"]
  node_feature_engineering["Feature engineering"]
  node_imbalance_handling["SMOTE balancing"]
  node_model_comparison["Model comparison"]
end

subgraph group_inference["Risk prediction"]
  node_trained_model["XGBoost model<br/>[xgb_model.pkl]"]
  node_scaler["Feature scaler<br/>[scaler.pkl]"]
  node_feature_schema["Feature schema<br/>[feature_names.pkl]"]
  node_dashboard["Streamlit dashboard<br/>[app.py]"]
  node_profile_input["Customer profile<br/>[app.py]"]
  node_feature_preparation["Encode and scale<br/>[app.py]"]
  node_risk_score["Churn probability<br/>[app.py]"]
  node_risk_display["Risk result<br/>[app.py]"]
end

subgraph group_explanation["Prediction explanation"]
  node_shap_analysis["SHAP analysis<br/>[app.py]"]
  node_explanation_plot["Feature impact plot<br/>[app.py]"]
end

node_analyst(("Analyst"))

node_analyst -->|"uses"| node_dashboard
node_dashboard -->|"collects"| node_profile_input
node_dashboard -->|"loads"| node_feature_schema
node_dashboard -->|"loads"| node_trained_model
node_dashboard -->|"loads"| node_scaler
node_dashboard -->|"prepares features"| node_feature_preparation
node_profile_input -->|"provides values"| node_feature_preparation
node_feature_schema -->|"defines columns"| node_feature_preparation
node_scaler -->|"scales values"| node_feature_preparation
node_dashboard -->|"predicts probability"| node_trained_model
node_feature_preparation -->|"provides features"| node_trained_model
node_dashboard -->|"renders"| node_risk_display
node_trained_model -->|"returns probability"| node_risk_score
node_risk_score -->|"sets risk band"| node_risk_display
node_dashboard -->|"explains prediction"| node_shap_analysis
node_trained_model -->|"explains with model"| node_shap_analysis
node_feature_preparation -->|"provides features"| node_shap_analysis
node_shap_analysis -->|"produces"| node_explanation_plot
node_analyst -.->|"provides data"| node_raw_data
node_raw_data -->|"analyzes"| node_notebook
node_notebook -->|"performs EDA"| node_feature_engineering
node_feature_engineering -->|"creates features"| node_imbalance_handling
node_imbalance_handling -->|"balances data"| node_model_comparison
node_model_comparison -->|"selects XGBoost"| node_trained_model

click node_raw_data "https://github.com/akshayetukuri/customer-churn-predictor/blob/main/archive/Telco_customer_churn.xlsx"
click node_notebook "https://github.com/akshayetukuri/customer-churn-predictor/blob/main/churn_prediction.ipynb"
click node_feature_engineering "https://github.com/akshayetukuri/customer-churn-predictor/blob/main/churn_prediction.ipynb"
click node_imbalance_handling "https://github.com/akshayetukuri/customer-churn-predictor/blob/main/churn_prediction.ipynb"
click node_model_comparison "https://github.com/akshayetukuri/customer-churn-predictor/blob/main/churn_prediction.ipynb"
click node_trained_model "https://github.com/akshayetukuri/customer-churn-predictor/blob/main/xgb_model.pkl"
click node_scaler "https://github.com/akshayetukuri/customer-churn-predictor/blob/main/scaler.pkl"
click node_feature_schema "https://github.com/akshayetukuri/customer-churn-predictor/blob/main/feature_names.pkl"
click node_dashboard "https://github.com/akshayetukuri/customer-churn-predictor/blob/main/app.py"
click node_profile_input "https://github.com/akshayetukuri/customer-churn-predictor/blob/main/app.py"
click node_feature_preparation "https://github.com/akshayetukuri/customer-churn-predictor/blob/main/app.py"
click node_risk_score "https://github.com/akshayetukuri/customer-churn-predictor/blob/main/app.py"
click node_risk_display "https://github.com/akshayetukuri/customer-churn-predictor/blob/main/app.py"
click node_shap_analysis "https://github.com/akshayetukuri/customer-churn-predictor/blob/main/app.py"
click node_explanation_plot "https://github.com/akshayetukuri/customer-churn-predictor/blob/main/app.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_raw_data,node_notebook,node_feature_engineering,node_imbalance_handling,node_model_comparison toneBlue
class node_trained_model,node_scaler,node_feature_schema,node_dashboard,node_profile_input,node_feature_preparation,node_risk_score,node_risk_display toneAmber
class node_shap_analysis,node_explanation_plot toneMint
class node_analyst toneIndigo
```

## Components

### Data and modeling

- [Customer dataset](https://github.com/akshayetukuri/customer-churn-predictor/blob/main/archive/Telco_customer_churn.xlsx): `archive/Telco_customer_churn.xlsx`
- [EDA and modeling](https://github.com/akshayetukuri/customer-churn-predictor/blob/main/churn_prediction.ipynb): `churn_prediction.ipynb`
- [Feature engineering](https://github.com/akshayetukuri/customer-churn-predictor/blob/main/churn_prediction.ipynb): `churn_prediction.ipynb`
- [SMOTE balancing](https://github.com/akshayetukuri/customer-churn-predictor/blob/main/churn_prediction.ipynb): `churn_prediction.ipynb`
- [Model comparison](https://github.com/akshayetukuri/customer-churn-predictor/blob/main/churn_prediction.ipynb): `churn_prediction.ipynb`

### Risk prediction

- [XGBoost model](https://github.com/akshayetukuri/customer-churn-predictor/blob/main/xgb_model.pkl): `xgb_model.pkl`
- [Feature scaler](https://github.com/akshayetukuri/customer-churn-predictor/blob/main/scaler.pkl): `scaler.pkl`
- [Feature schema](https://github.com/akshayetukuri/customer-churn-predictor/blob/main/feature_names.pkl): `feature_names.pkl`
- [Streamlit dashboard](https://github.com/akshayetukuri/customer-churn-predictor/blob/main/app.py): `app.py`
- [Customer profile](https://github.com/akshayetukuri/customer-churn-predictor/blob/main/app.py): `app.py`
- [Encode and scale](https://github.com/akshayetukuri/customer-churn-predictor/blob/main/app.py): `app.py`
- [Churn probability](https://github.com/akshayetukuri/customer-churn-predictor/blob/main/app.py): `app.py`
- [Risk result](https://github.com/akshayetukuri/customer-churn-predictor/blob/main/app.py): `app.py`

### Prediction explanation

- [SHAP analysis](https://github.com/akshayetukuri/customer-churn-predictor/blob/main/app.py): `app.py`
- [Feature impact plot](https://github.com/akshayetukuri/customer-churn-predictor/blob/main/app.py): `app.py`

### Other components

- **Analyst**

## Connections

- Analyst → Streamlit dashboard: uses
- Streamlit dashboard → Customer profile: collects
- Streamlit dashboard → Feature schema: loads
- Streamlit dashboard → XGBoost model: loads
- Streamlit dashboard → Feature scaler: loads
- Streamlit dashboard → Encode and scale: prepares features
- Customer profile → Encode and scale: provides values
- Feature schema → Encode and scale: defines columns
- Feature scaler → Encode and scale: scales values
- Streamlit dashboard → XGBoost model: predicts probability
- Encode and scale → XGBoost model: provides features
- Streamlit dashboard → Risk result: renders
- XGBoost model → Churn probability: returns probability
- Churn probability → Risk result: sets risk band
- Streamlit dashboard → SHAP analysis: explains prediction
- XGBoost model → SHAP analysis: explains with model
- Encode and scale → SHAP analysis: provides features
- SHAP analysis → Feature impact plot: produces
- Analyst → Customer dataset: provides data
- Customer dataset → EDA and modeling: analyzes
- EDA and modeling → Feature engineering: performs EDA
- Feature engineering → SMOTE balancing: creates features
- SMOTE balancing → Model comparison: balances data
- Model comparison → XGBoost model: selects XGBoost