# akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning architecture

> Architecture diagram of the GitHub repository akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning
- Repository: https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning

## Overview

This repository is a Streamlit customer-churn application combining churn-risk prediction, customer segmentation, and AI-generated retention recommendations. The principal workflow is customer input in the dashboard, API prediction, and recommendation display. A separate preparation and model-training workflow creates the artifacts used at runtime. Source excerpts support the model and recommendation internals; the README documents the intended setup sequence, while some UI call details are unsampled.

Main entry points: [`api.py`](https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/api.py) (Prediction API), [`unsupervised.py`](https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/unsupervised.py) (Segmentation Training), [`prepped_data.csv`](https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/prepped_data.csv) (Prepared Data), [`get_recom.py`](https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/get_recom.py) (Recommendation Generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_training["Data and Training"]
  node_raw_data["Churn Dataset"]
  node_preprocessing["Data Preparation<br/>[prep_data.py]"]
  node_prepared_data["Prepared Data<br/>[prepped_data.csv]"]
  node_cluster_selection["Cluster Selection<br/>[choosing_best_k.py]"]
  node_cluster_config["Selected K<br/>[best_k.json]"]
  node_segmentation_training["Segmentation Training<br/>[unsupervised.py]"]
  node_classification_data["Classification Data"]
  node_churn_training["Churn Model Training<br/>[supervised.py]"]
  node_segment_model["K-Means Model<br/>[kmeans_model.pkl]"]
  node_churn_model["Random Forest Model"]
end

subgraph group_runtime["Prediction Runtime"]
  node_prediction_api["Prediction API<br/>[api.py]"]
end

subgraph group_recommendations["Recommendations"]
  node_recommendation_logic["Recommendation Generator<br/>[get_recom.py]"]
  node_recommendation_schema["Response Schemas<br/>[schemas.py]"]
end

subgraph group_presentation["Dashboard"]
  node_dashboard["Streamlit Dashboard<br/>[UI.py]"]
end

node_customer(("Business User"))
node_gemini{{"Google Gemini"}}

node_customer -->|"enters customer data"| node_dashboard
node_dashboard -->|"requests prediction"| node_prediction_api
node_dashboard -->|"imports generator"| node_recommendation_logic
node_prediction_api -->|"loads and predicts"| node_segment_model
node_prediction_api -->|"loads and predicts"| node_churn_model
node_prediction_api -->|"reads feature columns"| node_classification_data
node_recommendation_logic -->|"formats response"| node_recommendation_schema
node_recommendation_logic -->|"requests recommendations"| node_gemini
node_raw_data -->|"provides source data"| node_preprocessing
node_preprocessing -->|"writes prepared data"| node_prepared_data
node_prepared_data -->|"supplies clustering data"| node_cluster_selection
node_cluster_selection -->|"writes selected K"| node_cluster_config
node_prepared_data -->|"supplies training data"| node_segmentation_training
node_cluster_config -->|"configures cluster count"| node_segmentation_training
node_segmentation_training -->|"writes segmented data"| node_classification_data
node_segmentation_training -->|"saves pipeline"| node_segment_model
node_classification_data -->|"supplies training data"| node_churn_training
node_churn_training -->|"saves classifier"| node_churn_model

click node_raw_data "https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/Bank%20Customer%20Churn%20Prediction.csv"
click node_preprocessing "https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/prep_data.py"
click node_prepared_data "https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/prepped_data.csv"
click node_cluster_selection "https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/choosing_best_k.py"
click node_cluster_config "https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/best_k.json"
click node_segmentation_training "https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/unsupervised.py"
click node_classification_data "https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/data_for%20classification.csv"
click node_churn_training "https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/supervised.py"
click node_segment_model "https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/kmeans_model.pkl"
click node_churn_model "https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/random_forest_clf.pkl"
click node_dashboard "https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/UI.py"
click node_prediction_api "https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/api.py"
click node_recommendation_logic "https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/get_recom.py"
click node_recommendation_schema "https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/schemas.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_preprocessing,node_prepared_data,node_cluster_selection,node_cluster_config,node_segmentation_training,node_classification_data,node_churn_training,node_segment_model,node_churn_model,node_customer toneBlue
class node_prediction_api toneAmber
class node_recommendation_logic,node_recommendation_schema toneMint
class node_dashboard toneRose
class node_gemini toneIndigo
```

## Components

### Data and Training

- [Churn Dataset](https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/Bank%20Customer%20Churn%20Prediction.csv): `Bank Customer Churn Prediction.csv`
- [Data Preparation](https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/prep_data.py): `prep_data.py`
- [Prepared Data](https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/prepped_data.csv): `prepped_data.csv`
- [Cluster Selection](https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/choosing_best_k.py): `choosing_best_k.py`
- [Selected K](https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/best_k.json): `best_k.json`
- [Segmentation Training](https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/unsupervised.py): `unsupervised.py`
- [Classification Data](https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/data_for%20classification.csv): `data_for classification.csv`
- [Churn Model Training](https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/supervised.py): `supervised.py`
- [K-Means Model](https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/kmeans_model.pkl): `kmeans_model.pkl`
- [Random Forest Model](https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/random_forest_clf.pkl): `random_forest_clf.pkl`

### Prediction Runtime

- [Prediction API](https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/api.py): `api.py`

### Recommendations

- [Recommendation Generator](https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/get_recom.py): `get_recom.py`
- [Response Schemas](https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/schemas.py): `schemas.py`

### Dashboard

- [Streamlit Dashboard](https://github.com/akchiche-mohamed-aymen/customer-churn-prediction-segmentation-using-machine-learning/blob/main/UI.py): `UI.py`

### Other components

- **Business User**
- **Google Gemini**

## Connections

- Business User → Streamlit Dashboard: enters customer data (evidence: `README.md`)
- Streamlit Dashboard → Prediction API: requests prediction (evidence: `UI.py`)
- Streamlit Dashboard → Recommendation Generator: imports generator (evidence: `UI.py`)
- Prediction API → K-Means Model: loads and predicts (evidence: `api.py`)
- Prediction API → Random Forest Model: loads and predicts (evidence: `api.py`)
- Prediction API → Classification Data: reads feature columns (evidence: `api.py`)
- Recommendation Generator → Response Schemas: formats response (evidence: `get_recom.py`)
- Recommendation Generator → Google Gemini: requests recommendations (evidence: `get_recom.py`)
- Churn Dataset → Data Preparation: provides source data (evidence: `prep_data.py`)
- Data Preparation → Prepared Data: writes prepared data (evidence: `prep_data.py`)
- Prepared Data → Cluster Selection: supplies clustering data (evidence: `choosing_best_k.py`)
- Cluster Selection → Selected K: writes selected K (evidence: `choosing_best_k.py`)
- Prepared Data → Segmentation Training: supplies training data (evidence: `unsupervised.py`)
- Selected K → Segmentation Training: configures cluster count (evidence: `unsupervised.py`)
- Segmentation Training → Classification Data: writes segmented data (evidence: `unsupervised.py`)
- Segmentation Training → K-Means Model: saves pipeline (evidence: `unsupervised.py`)
- Classification Data → Churn Model Training: supplies training data (evidence: `supervised.py`)
- Churn Model Training → Random Forest Model: saves classifier (evidence: `supervised.py`)
