# amitkashyap-21/churn-predictor-ml architecture

> Architecture diagram of the GitHub repository amitkashyap-21/churn-predictor-ml, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amitkashyap-21/churn-predictor-ml
- Repository: https://github.com/amitkashyap-21/churn-predictor-ml

## Overview

##### Project type and purpose — short summary
- This is an end‑to‑end ML project for binary classification: telecom Customer Churn Prediction.
- Purpose: build a complete ML pipeline (EDA → preprocess → train → evaluate → explain) and provide an interactive Streamlit UI for live prediction. It’s primarily a research/POC repo that contains both exploratory notebooks and lightweight production artifacts (scripts, a saved model, and a Streamlit app).

##### Key evidence from README + file tree
- app.py — Streamlit app used to serve predictions (interactive frontend).
- src/*.py — productionable scripts: preprocess.py, predict.py, evaluate.py, train.py (train.py exists as notebook and script).
- data/raw & data/processed — raw CSV input and processed CSV.
- models/churn_model.pkl — trained model artifact used by app and predict.py.
- notebooks/* — EDA, preprocessing, modeling, explainability (SHAP) pipelines used during development.
- outputs — figures and reports from notebooks.
- requirements.txt — dependency list (scikit-learn, pandas, numpy, streamlit, shap, etc.).

##### How I would represent the system

- data/raw/WA_Fn-UseC_-Telco-Customer-Churn.csv (label: Raw CSV)
- Optional: external source (Kaggle URL) as cloud/external data source

- src/preprocess.py and notebooks/02_preprocessing.ipynb
- Inputs: raw CSV → Outputs: data/processed/churn_clean.csv
- Include preprocessing functions/pipeline (categorical encoding, imputation, scaling) that are reused at inference.

- src/train.py and notebooks/03_modeling.ipynb
- Inputs: processed CSV → outputs: models/churn_model.pkl and evaluation metrics to outputs/
- Models trained: LogisticRegression, RandomForest, GradientBoosting (annotate best model)

- src/evaluate.py and notebooks/04_explainability.ipynb
- Tools: sklearn metrics, SHAP
- Outputs: ROC-AUC, confusion matrix, SHAP plots → outputs/

- models/churn_model.pkl (artifact)
- Versioning/metadata (timestamp, metrics)

- app.py (Streamlit app)
- src/predict.py (inference helper)
- Runtime: Streamlit server (http://localhost:8501)
- Inputs: user-entered customer attributes OR preprocessed records
- Uses: preprocessing pipeline (same transformations) + loaded churn_model.pkl → output: churn probability + SHAP explanation

- notebooks/* — exploratory work, reproducibility, ad‑hoc analysis; create artifacts used by other components (processed data, figures)

- Outputs (file system / reporting)
- outputs/figures and outputs/reports created by notebooks/evaluation

- CLI: "streamlit run app.py", "python src/train.py"
- requirements.txt for environment
- Future: FastAPI or containerization/CI-CD (annotate as “future improvement”)

- Raw data → Preprocessing (label: CSV ingestion, cleaning)
- Preprocessing → Processed data (churn_clean.csv)
- Processed data → Training (label: batch training; frequency: ad-hoc / nightly)
- Training → Model artifact (churn_model.pkl) and Evaluation metrics → Outputs
- Training/Evaluation → Explainability (SHAP) → Outputs/Reports
- Model artifact + Preprocessing pipeline → Serving (Streamlit app)
- User input → Serving → Predict (inference) → Output to user (probability + SHAP)

##### Architectural patterns / design principles to call out
- Separation of concerns: data layer (data/), processing layer (src/preprocess.py), training layer (src/train.py), evaluation/explainability (src/evaluate.py / SHAP notebooks), serving (app.py + src/predict.py).
- Reuse of preprocessing: preprocessing logic must be reusable/invariant across train and serve — emphasize packaging preprocessing code so the same transformations used during train are applied at inference.
- Artifact-driven workflow: explicit model artifact (pickle) saved to models/ and consumed by app.py.
- Offline batch training + online inference: training is batch (not real-time); inference is synchronous (Streamlit UI) or could be converted to REST API later.
- Reproducibility: notebooks produce processed data and outputs; requirements.txt pins environment.

- Python (runtime)
- Data: pandas, numpy (CSV read/write)
- ML: scikit-learn (models), joblib/pickle for serialization
- Explainability: SHAP
- Serving: Streamlit (app.py)
- Optional infra / future: FastAPI (for production API), Docker/Kubernetes, cloud storage (S3), model registry (MLflow)

##### Extra suggestions to improve fidelity
- A “Preprocessing contract” note — show that the same preprocessing functions must be shared between train and serve; indicate location in repo (src/preprocess.py).
- Where model metrics and artifacts are recorded (outputs/ and models/); annotate with a pointer to evaluation notebook outputs/figures.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-down layout
    classDef datastore fill:#cce5ff,stroke:#2b78d2,color:#03396c;
    classDef process fill:#d4f4dd,stroke:#2b8a3e,color:#0b6623;
    classDef ui fill:#ffd9b3,stroke:#ff8c1a,color:#7a3e00;
    classDef notebook fill:#f0f0f0,stroke:#9e9e9e,color:#444444,stroke-dasharray: 5 5;
    classDef artifact fill:#cfe2ff,stroke:#3973b5,color:#08306b;
    classDef external fill:#efe0ff,stroke:#8b5fbf,color:#40235a;
    classDef note fill:#fff5cc,stroke:#d6b200,color:#6a4a00;
    classDef legend fill:#ffffff,stroke:#dddddd,color:#000000;

    %% Data sources (top)
    subgraph "Data Sources" 
        direction TB
        RAW["Raw CSV\ndata/raw/WA_Fn-UseC_-Telco-Customer-Churn.csv"]:::datastore
        EXTERNAL["External Data (Kaggle)"]:::external
    end

    %% Preprocessing
    subgraph "Preprocessing / ETL" 
        direction TB
        PREPROCESS["Preprocessing — src/preprocess.py\n(encoders, imputation, scaling)\nOutputs: churn_clean.csv"]:::process
        PROCESSED["Processed CSV\ndata/processed/churn_clean.csv"]:::datastore
    end

    %% Training, Evaluation, Explainability cluster
    subgraph "Training & Evaluation" 
        direction TB
        TRAIN_SCRIPT["Training Script — src/train.py\n(notebook: notebooks/03_modeling.ipynb)\nModels: LR / RF / GBM"]:::process
        EVALUATE["Evaluation — src/evaluate.py\nMetrics: ROC-AUC, precision, recall"]:::process
        SHAP_NOTEBOOK["Explainability — notebooks/04_explainability.ipynb\n(SHAP plots)"]:::notebook
        MODEL["Model Artifact\nmodels/churn_model.pkl"]:::artifact
        OUTPUTS["Outputs / Reports / Figures\noutputs/"]:::datastore
    end

    %% Serving / Inference
    subgraph "Serving (Online Inference)" 
        direction TB
        STREAMLIT["Streamlit UI — app.py\n(http://localhost:8501)"]:::ui
        PREDICT_HELPER["Inference Helper — src/predict.py\n(loads preprocess + model)"]:::process
        USER["End User\n(web UI)"]:::external
    end

    %% Notebooks / Development (dashed)
    subgraph "Notebooks (Exploration, Research)" 
        direction TB
        NB_EDA["notebooks/01_eda.ipynb"]:::notebook
        NB_PREP["notebooks/02_preprocessing.ipynb"]:::notebook
        NB_MODEL["notebooks/03_modeling.ipynb"]:::notebook
        NB_EXPL["notebooks/04_explainability.ipynb"]:::notebook
        NB_CHECKS["notebooks/.ipynb_checkpoints/"]:::notebook
    end

    %% Auxiliary / Repo metadata
    REQS["requirements.txt\n(pandas,numpy,scikit-learn,shap,streamlit)"]:::note
    CHECKS["src/.ipynb_checkpoints/"]:::note

    %% Connections - data lineage (top to center)
    EXTERNAL -->|"download CSV (ad-hoc)"| RAW
    RAW -->|"CSV ingestion / cleaning"| PREPROCESS
    PREPROCESS -->|"writes CSV (batch/ad-hoc)\nchurn_clean.csv"| PROCESSED

    %% Preprocessed to training
    PROCESSED -->|"batch training (ad-hoc)\nCSV"| TRAIN_SCRIPT
    TRAIN_SCRIPT -->|"saves model (pickle)\nmodels/churn_model.pkl"| MODEL
    TRAIN_SCRIPT -->|"evaluation metrics"| EVALUATE
    EVALUATE -->|"metrics & figures"| OUTPUTS
    TRAIN_SCRIPT -->|"training traces / artifacts"| OUTPUTS
    SHAP_NOTEBOOK -->|"SHAP plots"| OUTPUTS

    %% Explainability path
    MODEL -->|"used by SHAP analysis"| SHAP_NOTEBOOK
    PROCESSED -->|"used by explainability notebooks"| SHAP_NOTEBOOK

    %% Model to serving/inference
    MODEL -->|"pickle (models/churn_model.pkl)\nversioned artifact"| PREDICT_HELPER
    PREPROCESS -->|"reused transformations\n(src/preprocess.py) — Preprocessing contract"| PREDICT_HELPER
    PREDICT_HELPER -->|"inference (JSON/struct)\nprobability + SHAP values"| STREAMLIT
    USER -->|"interacts via web UI (inputs)"| STREAMLIT
    STREAMLIT -->|"calls predict helper (sync)"| PREDICT_HELPER
    STREAMLIT -->|"renders probability + SHAP visuals"| USER

    %% Notebooks influence production scripts (dashed)
    NB_PREP -.->|"research → production\ncode & patterns"| PREPROCESS
    NB_MODEL -.->|"experiments → src/train.py"| TRAIN_SCRIPT
    NB_EXPL -.->|"experiments → src/evaluate.py\nand outputs"| EVALUATE
    NB_EDA -.->|"EDA insights"| NB_PREP

    %% Developer actions / commands (dashed)
    REQS -.->|"environment"| STREAMLIT
    REQS -.->|"environment"| TRAIN_SCRIPT
    CHECKS -.->|"editor checkpoints"| PREPROCESS
    CHECKS -.->|"editor checkpoints"| PREDICT_HELPER

    %% Future/proposed infra (optional)
    DEPLOY["Future: REST API (FastAPI), Docker, CI/CD\nModel Registry (MLflow)"]:::external
    MODEL -->|"promote model (future)"| DEPLOY
    DEPLOY -.->|"serving / containerized API"| STREAMLIT

    %% Legend
    subgraph "Legend" 
        direction TB
        L1["Cylinders = Data & Artifacts"]:::datastore
        L2["Green boxes = Compute (scripts/jobs)"]:::process
        L3["Orange rounded = Serving / UI"]:::ui
        L4["Gray dashed = Notebooks / Research"]:::notebook
        L5["Purple = External / Future infra"]:::external
    end

    %% Click events for mapped components
    click RAW "https://github.com/amitkashyap-21/churn-predictor-ml/blob/main/data/raw/WA_Fn-UseC_-Telco-Customer-Churn.csv"
    click PROCESSED "https://github.com/amitkashyap-21/churn-predictor-ml/blob/main/data/processed/churn_clean.csv"
    click PREPROCESS "https://github.com/amitkashyap-21/churn-predictor-ml/blob/main/src/preprocess.py"
    click TRAIN_SCRIPT "https://github.com/amitkashyap-21/churn-predictor-ml/blob/main/src/train.py"
    click NB_MODEL "https://github.com/amitkashyap-21/churn-predictor-ml/blob/main/notebooks/03_modeling.ipynb"
    click MODEL "https://github.com/amitkashyap-21/churn-predictor-ml/blob/main/models/churn_model.pkl"
    click EVALUATE "https://github.com/amitkashyap-21/churn-predictor-ml/blob/main/src/evaluate.py"
    click SHAP_NOTEBOOK "https://github.com/amitkashyap-21/churn-predictor-ml/blob/main/notebooks/04_explainability.ipynb"
    click OUTPUTS "https://github.com/amitkashyap-21/churn-predictor-ml/tree/main/outputs/"
    click PREDICT_HELPER "https://github.com/amitkashyap-21/churn-predictor-ml/blob/main/src/predict.py"
    click STREAMLIT "https://github.com/amitkashyap-21/churn-predictor-ml/blob/main/app.py"
    click NB_EDA "https://github.com/amitkashyap-21/churn-predictor-ml/blob/main/notebooks/01_eda.ipynb"
    click NB_PREP "https://github.com/amitkashyap-21/churn-predictor-ml/blob/main/notebooks/02_preprocessing.ipynb"
    click REQS "https://github.com/amitkashyap-21/churn-predictor-ml/blob/main/requirements.txt"
    click CHECKS "https://github.com/amitkashyap-21/churn-predictor-ml/tree/main/src/.ipynb_checkpoints/"
    click NB_CHECKS "https://github.com/amitkashyap-21/churn-predictor-ml/tree/main/notebooks/.ipynb_checkpoints/"

    %% Classes application (explicit)
    class RAW,PROCESSED,MODEL,OUTPUTS datastore
    class PREPROCESS,TRAIN_SCRIPT,EVALUATE,PREDICT_HELPER process
    class STREAMLIT ui
    class NB_EDA,NB_PREP,NB_MODEL,NB_EXPL,NB_CHECKS notebook
    class DEPLOY external
    class REQS,CHECKS note
```
