# mdareeb01/customer-churn-prediction-system architecture

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

- Interactive diagram: https://gitdiagram.com/mdareeb01/customer-churn-prediction-system
- Repository: https://github.com/mdareeb01/customer-churn-prediction-system

## Overview

This is a telecom customer churn analytics product: users enter customer details in the Streamlit app, receive an XGBoost prediction with probability and risk, can request an AI interpretation, and can save and explore predictions. The documented data workflow also covers cleaning, feature engineering, model comparison, and evaluation; Power BI provides broader business dashboards. Notebook-to-artifact implementation details were not sampled, so those workflow links follow the README rather than inspected code.

Main entry points: [`app/app.py`](https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/app/app.py) (Streamlit application), [`data/processed/Telco-Customer-Churn-Clean.csv`](https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/data/processed/Telco-Customer-Churn-Clean.csv) (Cleaned data), [`powerbi/customer_churn_dashboard.pbix`](https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/powerbi/customer_churn_dashboard.pbix) (Power BI dashboards), [`notebooks/01_Data_Understanding_&_Cleaning.ipynb`](https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/notebooks/01_Data_Understanding_%26_Cleaning.ipynb) (Cleaning and EDA)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Data and modeling"]
  node_raw_data["Raw telecom data"]
  node_cleaning["Cleaning and EDA"]
  node_clean_data["Cleaned data"]
  node_features["Feature engineering"]
  node_model_comparison["Model comparison"]
  node_comparison_results["Comparison results"]
  node_model["XGBoost predictor<br/>[prediction.py]"]
  node_model_files["Model and scaler<br/>[xgboost_model.pkl]"]
end

subgraph group_application["Streamlit application"]
  node_app["Streamlit application<br/>[app.py]"]
  node_ai["Churn explanation<br/>[ai_assistant.py]"]
  node_history["Prediction history<br/>[database.py]"]
end

subgraph group_insights["Business insights"]
  node_performance["Model performance"]
  node_evaluation_data["Evaluation artifacts<br/>[model_metrics.pkl]"]
  node_powerbi["Power BI dashboards"]
end

subgraph group_integrations["External services"]
  node_mysql[("MySQL predictions")]
  node_groq{{"Groq API"}}
end

node_user(("Business user"))

node_raw_data -->|"clean and explore"| node_cleaning
node_cleaning -->|"produce cleaned data"| node_clean_data
node_clean_data -->|"engineer features"| node_features
node_features -->|"evaluate models"| node_model_comparison
node_comparison_results -->|"load comparisons"| node_model_comparison
node_user -->|"enter customer details"| node_app
node_app -->|"request prediction"| node_model
node_model_files -->|"load model assets"| node_model
node_app -->|"request explanation"| node_ai
node_ai -.->|"request analysis"| node_groq
node_app -->|"save or retrieve"| node_history
node_history -->|"write and read"| node_mysql
node_app -->|"show evaluation"| node_performance
node_evaluation_data -->|"load metrics and curves"| node_performance
node_user -->|"explore dashboards"| node_powerbi
node_mysql -->|"provide prediction insights"| node_powerbi
node_clean_data -->|"support customer analytics"| node_powerbi

click node_raw_data "https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/data/raw/Telco_Customer_Churn.csv"
click node_cleaning "https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/notebooks/01_Data_Understanding_%26_Cleaning.ipynb"
click node_clean_data "https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/data/processed/Telco-Customer-Churn-Clean.csv"
click node_features "https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/notebooks/03_Feature_Engineering.ipynb"
click node_model_comparison "https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/app/model_comparison.py"
click node_comparison_results "https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/artifacts/model_comparison.csv"
click node_model "https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/app/prediction.py"
click node_model_files "https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/models/xgboost_model.pkl"
click node_app "https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/app/app.py"
click node_ai "https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/app/ai_assistant.py"
click node_history "https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/app/database.py"
click node_performance "https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/app/model_performance.py"
click node_evaluation_data "https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/artifacts/model_metrics.pkl"
click node_powerbi "https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/powerbi/customer_churn_dashboard.pbix"

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_cleaning,node_clean_data,node_features,node_model_comparison,node_comparison_results,node_model,node_model_files,node_user toneBlue
class node_app,node_ai,node_history toneAmber
class node_performance,node_evaluation_data,node_powerbi toneMint
class node_mysql,node_groq toneRose
```

## Components

### Data and modeling

- [Raw telecom data](https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/data/raw/Telco_Customer_Churn.csv): `data/raw/Telco_Customer_Churn.csv`
- [Cleaning and EDA](https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/notebooks/01_Data_Understanding_%26_Cleaning.ipynb): `notebooks/01_Data_Understanding_&_Cleaning.ipynb`
- [Cleaned data](https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/data/processed/Telco-Customer-Churn-Clean.csv): `data/processed/Telco-Customer-Churn-Clean.csv`
- [Feature engineering](https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/notebooks/03_Feature_Engineering.ipynb): `notebooks/03_Feature_Engineering.ipynb`
- [Model comparison](https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/app/model_comparison.py): `app/model_comparison.py`
- [Comparison results](https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/artifacts/model_comparison.csv): `artifacts/model_comparison.csv`
- [XGBoost predictor](https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/app/prediction.py): `app/prediction.py`
- [Model and scaler](https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/models/xgboost_model.pkl): `models/xgboost_model.pkl`

### Streamlit application

- [Streamlit application](https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/app/app.py): `app/app.py`
- [Churn explanation](https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/app/ai_assistant.py): `app/ai_assistant.py`
- [Prediction history](https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/app/database.py): `app/database.py`

### Business insights

- [Model performance](https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/app/model_performance.py): `app/model_performance.py`
- [Evaluation artifacts](https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/artifacts/model_metrics.pkl): `artifacts/model_metrics.pkl`
- [Power BI dashboards](https://github.com/mdareeb01/customer-churn-prediction-system/blob/main/powerbi/customer_churn_dashboard.pbix): `powerbi/customer_churn_dashboard.pbix`

### External services

- **MySQL predictions**
- **Groq API**

### Other components

- **Business user**

## Connections

- Raw telecom data → Cleaning and EDA: clean and explore
- Cleaning and EDA → Cleaned data: produce cleaned data
- Cleaned data → Feature engineering: engineer features
- Feature engineering → Model comparison: evaluate models
- Comparison results → Model comparison: load comparisons
- Business user → Streamlit application: enter customer details
- Streamlit application → XGBoost predictor: request prediction
- Model and scaler → XGBoost predictor: load model assets
- Streamlit application → Churn explanation: request explanation
- Churn explanation → Groq API: request analysis
- Streamlit application → Prediction history: save or retrieve
- Prediction history → MySQL predictions: write and read
- Streamlit application → Model performance: show evaluation
- Evaluation artifacts → Model performance: load metrics and curves
- Business user → Power BI dashboards: explore dashboards
- MySQL predictions → Power BI dashboards: provide prediction insights
- Cleaned data → Power BI dashboards: support customer analytics