# sad-jack/customer-churn-prediction architecture

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

- Interactive diagram: https://gitdiagram.com/sad-jack/customer-churn-prediction
- Repository: https://github.com/sad-jack/customer-churn-prediction

## Overview

This is a Telco customer-churn prediction project. Its main workflow loads and cleans the CSV, prepares features, compares classifiers, evaluates and selects a model, then saves an artifact for single-customer predictions in a Streamlit UI. A separate exploratory script summarizes the dataset. The source excerpts show the training and inference calls; generated model and report files are outputs, not present in the supplied tree.

Main entry points: [`src/train.py`](https://github.com/sad-jack/customer-churn-prediction/blob/main/src/train.py) (Model training orchestration), [`src/predict.py`](https://github.com/sad-jack/customer-churn-prediction/blob/main/src/predict.py) (Prediction service), [`app/streamlit_app.py`](https://github.com/sad-jack/customer-churn-prediction/blob/main/app/streamlit_app.py) (Customer profile UI), [`explore_dataset.py`](https://github.com/sad-jack/customer-churn-prediction/blob/main/explore_dataset.py) (Dataset explorer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data exploration"]
  node_dataset[("Telco churn CSV")]
  node_explorer["Dataset explorer<br/>[explore_dataset.py]"]
end

subgraph group_training["Model training"]
  node_config["Project configuration<br/>[config.py]"]
  node_loader["Load and clean data<br/>[data_loader.py]"]
  node_split["Feature and target split<br/>[data_loader.py]"]
  node_preprocess["Feature preprocessing<br/>[preprocess.py]"]
  node_train_entry["Training command<br/>[train_model.py]"]
  node_trainer["Model training orchestration<br/>[train.py]"]
  node_catalog["Classifier comparison<br/>[train.py]"]
  node_evaluation["Metrics and reports<br/>[evaluate.py]"]
  node_report_files["Training reports"]
end

subgraph group_inference["Prediction app"]
  node_artifact[("Saved model artifact")]
  node_app["Customer profile UI<br/>[streamlit_app.py]"]
  node_predict["Prediction service<br/>[predict.py]"]
  node_input_frame["Input feature frame<br/>[predict.py]"]
  node_risk["Risk classification<br/>[predict.py]"]
end

node_analyst(("Project user"))
node_streamlit_user(("App user"))

node_analyst -->|"inspects data"| node_explorer
node_explorer -->|"reads CSV"| node_dataset
node_analyst -->|"starts training"| node_train_entry
node_train_entry -->|"calls main"| node_trainer
node_trainer -->|"uses settings"| node_config
node_config -->|"locates CSV"| node_dataset
node_trainer -->|"loads and cleans"| node_loader
node_loader -->|"splits features"| node_split
node_trainer -->|"builds preprocessing"| node_preprocess
node_trainer -->|"fits candidates"| node_catalog
node_trainer -->|"evaluates candidates"| node_evaluation
node_trainer -->|"saves best model"| node_artifact
node_trainer -->|"writes reports"| node_report_files
node_streamlit_user -->|"enters profile"| node_app
node_app -->|"requests prediction"| node_predict
node_app -->|"loads cached model"| node_artifact
node_predict -->|"loads artifact"| node_artifact
node_predict -->|"builds input"| node_input_frame
node_predict -->|"derives risk level"| node_risk
node_predict -->|"returns result"| node_app

click node_dataset "https://github.com/sad-jack/customer-churn-prediction/blob/main/datasets/Telco-Customer-Churn.csv"
click node_explorer "https://github.com/sad-jack/customer-churn-prediction/blob/main/explore_dataset.py"
click node_config "https://github.com/sad-jack/customer-churn-prediction/blob/main/src/config.py"
click node_loader "https://github.com/sad-jack/customer-churn-prediction/blob/main/src/data_loader.py"
click node_split "https://github.com/sad-jack/customer-churn-prediction/blob/main/src/data_loader.py"
click node_preprocess "https://github.com/sad-jack/customer-churn-prediction/blob/main/src/preprocess.py"
click node_train_entry "https://github.com/sad-jack/customer-churn-prediction/blob/main/train_model.py"
click node_trainer "https://github.com/sad-jack/customer-churn-prediction/blob/main/src/train.py"
click node_catalog "https://github.com/sad-jack/customer-churn-prediction/blob/main/src/train.py"
click node_evaluation "https://github.com/sad-jack/customer-churn-prediction/blob/main/src/evaluate.py"
click node_app "https://github.com/sad-jack/customer-churn-prediction/blob/main/app/streamlit_app.py"
click node_predict "https://github.com/sad-jack/customer-churn-prediction/blob/main/src/predict.py"
click node_input_frame "https://github.com/sad-jack/customer-churn-prediction/blob/main/src/predict.py"
click node_risk "https://github.com/sad-jack/customer-churn-prediction/blob/main/src/predict.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_dataset,node_explorer,node_analyst,node_streamlit_user toneBlue
class node_config,node_loader,node_split,node_preprocess,node_train_entry,node_trainer,node_catalog,node_evaluation,node_report_files toneAmber
class node_artifact,node_app,node_predict,node_input_frame,node_risk toneMint
```

## Components

### Data exploration

- [Telco churn CSV](https://github.com/sad-jack/customer-churn-prediction/blob/main/datasets/Telco-Customer-Churn.csv): `datasets/Telco-Customer-Churn.csv`
- [Dataset explorer](https://github.com/sad-jack/customer-churn-prediction/blob/main/explore_dataset.py): `explore_dataset.py`

### Model training

- [Project configuration](https://github.com/sad-jack/customer-churn-prediction/blob/main/src/config.py): `src/config.py`
- [Load and clean data](https://github.com/sad-jack/customer-churn-prediction/blob/main/src/data_loader.py): `src/data_loader.py`
- [Feature and target split](https://github.com/sad-jack/customer-churn-prediction/blob/main/src/data_loader.py): `src/data_loader.py`
- [Feature preprocessing](https://github.com/sad-jack/customer-churn-prediction/blob/main/src/preprocess.py): `src/preprocess.py`
- [Training command](https://github.com/sad-jack/customer-churn-prediction/blob/main/train_model.py): `train_model.py`
- [Model training orchestration](https://github.com/sad-jack/customer-churn-prediction/blob/main/src/train.py): `src/train.py`
- [Classifier comparison](https://github.com/sad-jack/customer-churn-prediction/blob/main/src/train.py): `src/train.py`
- [Metrics and reports](https://github.com/sad-jack/customer-churn-prediction/blob/main/src/evaluate.py): `src/evaluate.py`
- **Training reports**

### Prediction app

- **Saved model artifact**
- [Customer profile UI](https://github.com/sad-jack/customer-churn-prediction/blob/main/app/streamlit_app.py): `app/streamlit_app.py`
- [Prediction service](https://github.com/sad-jack/customer-churn-prediction/blob/main/src/predict.py): `src/predict.py`
- [Input feature frame](https://github.com/sad-jack/customer-churn-prediction/blob/main/src/predict.py): `src/predict.py`
- [Risk classification](https://github.com/sad-jack/customer-churn-prediction/blob/main/src/predict.py): `src/predict.py`

### Other components

- **Project user**
- **App user**

## Connections

- Project user → Dataset explorer: inspects data (evidence: `explore_dataset.py`)
- Dataset explorer → Telco churn CSV: reads CSV (evidence: `explore_dataset.py`)
- Project user → Training command: starts training (evidence: `README.md`)
- Training command → Model training orchestration: calls main (evidence: `train_model.py`)
- Model training orchestration → Project configuration: uses settings (evidence: `src/train.py`)
- Project configuration → Telco churn CSV: locates CSV (evidence: `src/config.py`)
- Model training orchestration → Load and clean data: loads and cleans (evidence: `src/train.py`)
- Load and clean data → Feature and target split: splits features (evidence: `src/data_loader.py`)
- Model training orchestration → Feature preprocessing: builds preprocessing (evidence: `src/train.py`)
- Model training orchestration → Classifier comparison: fits candidates (evidence: `src/train.py`)
- Model training orchestration → Metrics and reports: evaluates candidates (evidence: `src/train.py`)
- Model training orchestration → Saved model artifact: saves best model (evidence: `src/train.py`)
- Model training orchestration → Training reports: writes reports (evidence: `src/train.py`)
- App user → Customer profile UI: enters profile (evidence: `app/streamlit_app.py`)
- Customer profile UI → Prediction service: requests prediction (evidence: `app/streamlit_app.py`)
- Customer profile UI → Saved model artifact: loads cached model (evidence: `app/streamlit_app.py`)
- Prediction service → Saved model artifact: loads artifact (evidence: `src/predict.py`)
- Prediction service → Input feature frame: builds input (evidence: `src/predict.py`)
- Prediction service → Risk classification: derives risk level (evidence: `src/predict.py`)
- Prediction service → Customer profile UI: returns result (evidence: `app/streamlit_app.py`)
