# vishnutpillai/telecom_churn_prediction architecture

> Architecture diagram of the GitHub repository vishnutpillai/telecom_churn_prediction, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vishnutpillai/telecom_churn_prediction
- Repository: https://github.com/vishnutpillai/telecom_churn_prediction

## Overview

#### Purpose and Runtime
This repository is a telecom customer churn prediction project. It trains/evaluates ML classifiers offline and exposes real-time churn predictions through a Streamlit application. Primary runtime entry point: `app.py`; training and analysis are represented by `Telecom_churn_prediction.ipynb`.

#### Offline Data and ML Workflow
The source dataset is `telecom_churn.csv`, containing customer account, service, billing, support, and churn-label data. The notebook `Telecom_churn_prediction.ipynb` is the authoritative offline workflow for cleaning, exploratory analysis, feature engineering, scaling, class-imbalance handling with SMOTE, model selection, and evaluation.

#### Model Selection and Training Boundary
Training compares Logistic Regression, Random Forest, and XGBoost models, with GridSearchCV used for hyperparameter selection. SMOTE and scaling are part of the intended ML pipeline, separating training-time preprocessing from raw source-data handling. The notebook produces deployable serialized artifacts rather than retraining during application requests: `Telecom_churn_prediction.ipynb`, `Best_model.pkl`.

#### Serialized Inference Contract
`Best_model.pkl` stores the selected trained model/pipeline used by the serving layer. `Column_order.pkl` defines the feature-column ordering expected by that model. Together they form the key inference contract: UI-entered customer attributes must be transformed into the exact trained feature schema and order before prediction.

#### Streamlit Serving Layer
`app.py` is the interactive deployment boundary. It collects customer inputs, applies the application-side input preparation needed to satisfy the artifact contract, loads `Best_model.pkl` and `Column_order.pkl`, and returns churn classification and probability-oriented output to the user. It is a synchronous local Streamlit service, not a separate API backend.

#### Control and Data Flow
1. Offline workflow reads `telecom_churn.csv` in `Telecom_churn_prediction.ipynb`.
2. Data is cleaned, encoded/engineered, scaled, and balanced; candidate models are tuned and evaluated.
3. The chosen model and expected feature ordering are persisted as `Best_model.pkl` and `Column_order.pkl`.
4. `app.py` accepts real-time customer values, aligns them to `Column_order.pkl`, invokes the loaded model, and presents churn risk.

#### Dependencies and External Surface
Python is the implementation runtime. Core libraries include pandas/NumPy, scikit-learn, imbalanced-learn, XGBoost, joblib, and Streamlit, declared in `requirements.txt`. The deployment target is Streamlit, including the linked hosted Streamlit demo; no database, message broker, or external prediction service is represented in the repository.

Main entry points: [`Telecom_churn_prediction.ipynb`](https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/Telecom_churn_prediction.ipynb) (Feature preparation), [`Best_model.pkl`](https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/Best_model.pkl) (Selected model), [`app.py`](https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/app.py) (Streamlit app), [`requirements.txt`](https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/requirements.txt) (Python dependencies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_offline["Offline ML workflow"]
  node_data[("Telecom churn data<br/>CSV dataset<br/>[telecom_churn.csv]")]
  node_notebook["Training notebook<br/>offline workflow"]
  node_feature_pipeline["Feature preparation<br/>cleaning and engineering"]
  node_smote["Class balancing<br/>SMOTE"]
  node_model_selection["Model selection<br/>GridSearchCV evaluation"]
end

subgraph group_artifacts["Inference artifacts"]
  node_best_model["Selected model<br/>serialized model pipeline<br/>[Best_model.pkl]"]
  node_column_order["Feature schema<br/>serialized column order<br/>[Column_order.pkl]"]
end

subgraph group_serving["Streamlit serving"]
  node_app["Streamlit app<br/>interactive entry point<br/>[app.py]"]
  node_input_prep["Input alignment<br/>serving preprocessing<br/>[app.py]"]
  node_prediction["Churn risk result<br/>classification and probability<br/>[app.py]"]
  node_user(("Customer input<br/>interactive user<br/>[app.py]"))
end

node_dependencies["Python dependencies<br/>runtime libraries<br/>[requirements.txt]"]

node_data -->|"read by"| node_notebook
node_notebook -->|"prepares data"| node_feature_pipeline
node_feature_pipeline -->|"training features"| node_smote
node_smote -->|"balanced training data"| node_model_selection
node_model_selection -->|"persists winner"| node_best_model
node_feature_pipeline -->|"defines feature order"| node_column_order
node_user -->|"enters customer values"| node_app
node_app -->|"prepares request"| node_input_prep
node_column_order -->|"aligns columns"| node_input_prep
node_input_prep -->|"model-ready features"| node_best_model
node_best_model -->|"classification and probability"| node_prediction
node_prediction -->|"presents churn risk"| node_user
node_dependencies -.->|"offline libraries"| node_notebook
node_dependencies -.->|"serving libraries"| node_app

click node_data "https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/telecom_churn.csv"
click node_notebook "https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/Telecom_churn_prediction.ipynb"
click node_feature_pipeline "https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/Telecom_churn_prediction.ipynb"
click node_smote "https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/Telecom_churn_prediction.ipynb"
click node_model_selection "https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/Telecom_churn_prediction.ipynb"
click node_best_model "https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/Best_model.pkl"
click node_column_order "https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/Column_order.pkl"
click node_app "https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/app.py"
click node_input_prep "https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/app.py"
click node_prediction "https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/app.py"
click node_user "https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/app.py"
click node_dependencies "https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/requirements.txt"

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_data,node_notebook,node_feature_pipeline,node_smote,node_model_selection toneBlue
class node_best_model,node_column_order toneAmber
class node_app,node_input_prep,node_prediction,node_user toneMint
class node_dependencies toneNeutral
```

## Components

### Offline ML workflow

- [Telecom churn data](https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/telecom_churn.csv): CSV dataset · Customer attributes and churn labels. · `telecom_churn.csv`
- [Training notebook](https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/Telecom_churn_prediction.ipynb): offline workflow · Authoritative training, analysis, and evaluation workflow. · `Telecom_churn_prediction.ipynb`
- [Feature preparation](https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/Telecom_churn_prediction.ipynb): cleaning and engineering · Cleans, encodes, and scales source features. · `Telecom_churn_prediction.ipynb`
- [Class balancing](https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/Telecom_churn_prediction.ipynb): SMOTE · Balances churn classes during training. · `Telecom_churn_prediction.ipynb`
- [Model selection](https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/Telecom_churn_prediction.ipynb): GridSearchCV evaluation · Compares Logistic Regression, Random Forest, and XGBoost. · `Telecom_churn_prediction.ipynb`

### Inference artifacts

- [Selected model](https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/Best_model.pkl): serialized model pipeline · Deployable trained inference model. · `Best_model.pkl`
- [Feature schema](https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/Column_order.pkl): serialized column order · Required model input feature ordering. · `Column_order.pkl`

### Streamlit serving

- [Streamlit app](https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/app.py): interactive entry point · Synchronous local real-time prediction service. · `app.py`
- [Input alignment](https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/app.py): serving preprocessing · Transforms UI values into the trained feature schema. · `app.py`
- [Churn risk result](https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/app.py): classification and probability · `app.py`
- [Customer input](https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/app.py): interactive user · `app.py`

### Other components

- [Python dependencies](https://github.com/vishnutpillai/telecom_churn_prediction/blob/main/requirements.txt): runtime libraries · Includes Streamlit, pandas, scikit-learn, imbalanced-learn, XGBoost, and joblib. · `requirements.txt`

## Connections

- Telecom churn data → Training notebook: read by
- Training notebook → Feature preparation: prepares data
- Feature preparation → Class balancing: training features
- Class balancing → Model selection: balanced training data
- Model selection → Selected model: persists winner
- Feature preparation → Feature schema: defines feature order
- Customer input → Streamlit app: enters customer values
- Streamlit app → Input alignment: prepares request
- Feature schema → Input alignment: aligns columns
- Input alignment → Selected model: model-ready features
- Selected model → Churn risk result: classification and probability
- Churn risk result → Customer input: presents churn risk
- Python dependencies → Training notebook: offline libraries
- Python dependencies → Streamlit app: serving libraries