# mahesh-pepali/customer-churn-prediction architecture

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

- Interactive diagram: https://gitdiagram.com/mahesh-pepali/customer-churn-prediction
- Repository: https://github.com/mahesh-pepali/customer-churn-prediction
- Video tour (about a minute): https://gitdiagram.com/mahesh-pepali/customer-churn-prediction/video

## Overview

This repository is a telecom customer-churn classification project, with a Streamlit interface as its user-facing product. Its main workflow cleans raw records, explores and prepares the data, trains and tunes classifiers, selects features and a decision threshold, then serves churn probabilities and decisions; evaluation reports classification metrics and plots. The README documents capabilities beyond the sampled training excerpt, including model serialization and tuning. Training internals are therefore summarized at the script level where details are incomplete; the documented model artifacts are not present in the supplied file tree.

Main entry points: [`src/train.py`](https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/train.py) (Model training), [`data/processed/cleaned_data.csv`](https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/data/processed/cleaned_data.csv) (Cleaned data), [`src/evaluate.py`](https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/evaluate.py) (Model evaluation), [`src/app.py`](https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/app.py) (Streamlit interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_preprocess["Data cleaning"]
  node_eda["Churn exploration<br/>[eda.py]"]
  node_features["Feature preparation"]
end

subgraph group_modeling["Model development"]
  node_training["Model training<br/>[train.py]"]
  node_imbalance["Class balancing<br/>[train.py]"]
  node_models["Classifier comparison<br/>[train.py]"]
  node_selection["Feature selection<br/>[train.py]"]
  node_tuning["Hyperparameter tuning<br/>[train.py]"]
  node_threshold["Threshold optimization<br/>[train.py]"]
end

subgraph group_serving["Prediction and evaluation"]
  node_bundle["Saved model and threshold<br/>[train.py]"]
  node_app["Streamlit interface<br/>[app.py]"]
  node_script["Prediction script<br/>[predict.py]"]
  node_evaluation["Model evaluation<br/>[evaluate.py]"]
  node_metrics["Metrics and plots<br/>[evaluate.py]"]
end

node_analyst(("Analyst"))
node_raw["Raw churn data<br/>[customer_churn.csv]"]
node_cleaned["Cleaned data<br/>[cleaned_data.csv]"]
node_user(("Prediction user"))

node_preprocess -->|"reads"| node_raw
node_preprocess -->|"writes"| node_cleaned
node_eda -->|"reads"| node_cleaned
node_features -->|"reads"| node_cleaned
node_training -->|"reads"| node_cleaned
node_training -->|"handles"| node_imbalance
node_training -->|"prepares"| node_features
node_training -->|"trains"| node_models
node_training -->|"selects"| node_selection
node_training -->|"tunes"| node_tuning
node_training -->|"optimizes"| node_threshold
node_training -->|"saves"| node_bundle
node_user -->|"enters details"| node_app
node_app -->|"loads"| node_bundle
node_app -->|"shows decision"| node_user
node_script -->|"loads"| node_bundle
node_evaluation -->|"loads"| node_bundle
node_evaluation -->|"reads"| node_cleaned
node_evaluation -->|"writes"| node_metrics

click node_raw "https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/data/raw/customer_churn.csv"
click node_preprocess "https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/data_preprocessing.py"
click node_cleaned "https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/data/processed/cleaned_data.csv"
click node_eda "https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/eda.py"
click node_features "https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/feature_engineering.py"
click node_training "https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/train.py"
click node_imbalance "https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/train.py"
click node_models "https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/train.py"
click node_selection "https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/train.py"
click node_tuning "https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/train.py"
click node_threshold "https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/train.py"
click node_bundle "https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/train.py"
click node_app "https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/app.py"
click node_script "https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/predict.py"
click node_evaluation "https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/evaluate.py"
click node_metrics "https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/evaluate.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_preprocess,node_eda,node_features,node_user toneBlue
class node_training,node_imbalance,node_models,node_selection,node_tuning,node_threshold toneAmber
class node_bundle,node_app,node_script,node_evaluation,node_metrics toneMint
class node_analyst toneIndigo
class node_raw,node_cleaned toneTeal
```

## Components

### Data preparation

- [Data cleaning](https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/data_preprocessing.py): `src/data_preprocessing.py`
- [Churn exploration](https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/eda.py): `src/eda.py`
- [Feature preparation](https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/feature_engineering.py): `src/feature_engineering.py`

### Model development

- [Model training](https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/train.py): `src/train.py`
- [Class balancing](https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/train.py): `src/train.py`
- [Classifier comparison](https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/train.py): `src/train.py`
- [Feature selection](https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/train.py): `src/train.py`
- [Hyperparameter tuning](https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/train.py): `src/train.py`
- [Threshold optimization](https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/train.py): `src/train.py`

### Prediction and evaluation

- [Saved model and threshold](https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/train.py): `src/train.py`
- [Streamlit interface](https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/app.py): `src/app.py`
- [Prediction script](https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/predict.py): `src/predict.py`
- [Model evaluation](https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/evaluate.py): `src/evaluate.py`
- [Metrics and plots](https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/src/evaluate.py): `src/evaluate.py`

### Other components

- **Analyst**
- [Raw churn data](https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/data/raw/customer_churn.csv): `data/raw/customer_churn.csv`
- [Cleaned data](https://github.com/mahesh-pepali/customer-churn-prediction/blob/main/data/processed/cleaned_data.csv): `data/processed/cleaned_data.csv`
- **Prediction user**

## Connections

- Data cleaning → Raw churn data: reads
- Data cleaning → Cleaned data: writes
- Churn exploration → Cleaned data: reads
- Feature preparation → Cleaned data: reads
- Model training → Cleaned data: reads
- Model training → Class balancing: handles
- Model training → Feature preparation: prepares
- Model training → Classifier comparison: trains
- Model training → Feature selection: selects
- Model training → Hyperparameter tuning: tunes
- Model training → Threshold optimization: optimizes
- Model training → Saved model and threshold: saves
- Prediction user → Streamlit interface: enters details
- Streamlit interface → Saved model and threshold: loads
- Streamlit interface → Prediction user: shows decision
- Prediction script → Saved model and threshold: loads
- Model evaluation → Saved model and threshold: loads
- Model evaluation → Cleaned data: reads
- Model evaluation → Metrics and plots: writes