# ayushsyntax/telecomchurnprediction architecture

> Architecture diagram of the GitHub repository ayushsyntax/telecomchurnprediction, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ayushsyntax/telecomchurnprediction
- Repository: https://github.com/ayushsyntax/telecomchurnprediction

## Overview

##### Project type and purpose
- This is a machine-learning-driven full-stack application for telecom customer churn prediction.
- It includes an offline training/EDA pipeline (Jupyter notebook), model persistence, a REST API backend (FastAPI via app.py), and an interactive frontend (Streamlit).

##### File structure
- Top-level:
- Telco_Customer_Churn.ipynb – exploratory data analysis, feature engineering, model training
- models/ – serialized artifacts (champion_model.pkl, kmeans.pkl, preprocessor.pkl, scaler.pkl)
- app.py – FastAPI application exposing prediction endpoints
- streamlit_app.py – Streamlit UI for users to input customer data, view churn probability & segment
- requirements.txt – dependency list
- No external DB: models are loaded from file system
- Configuration: .gitignore, LICENSE, README.md

##### Extract README insights
- Offline workflow: EDA → feature engineering → model selection (CatBoost) → clustering (K-Means) → SHAP interpretability → model persistence
- Deployment: joblib-pickled objects consumed by app.py & streamlit_app.py
- Tech stack: Python, scikit-learn, CatBoost, FastAPI, Uvicorn, Streamlit, SHAP

##### Main components
a. Offline Training Pipeline
- Jupyter Notebook (Telco_Customer_Churn.ipynb)
- Preprocessing module → Feature engineering → Model training (CatBoost) → Model evaluation → SHAP analysis → Model & artifacts persisted to file system (models/)
b. Model Artifact Store
- File system directory “models/” holding .pkl files
c. Backend API
- app.py (FastAPI + Uvicorn)
- Loads preprocessor.pkl, scaler.pkl, champion_model.pkl, kmeans.pkl
- Exposes endpoints: /predict (churn probability), /segment (K-Means cluster)
d. Frontend UI
- streamlit_app.py (Streamlit server)
- User inputs customer features
- Calls internal prediction functions or HTTP API to fetch churn score & segment
- Displays results and SHAP plots (optional)
e. End User
- Browser interacting with Streamlit
f. (Optional) CI/CD or retraining scheduler – not present but can be shown as future extension

##### Relationships & data flow
- Offline: Notebook → generate .pkl artifacts → models/
- At runtime:
- Streamlit UI loads artifacts OR calls FastAPI
- FastAPI loads artifacts into memory at startup
- User submits data → API receives POST → preprocessing → model.predict → returns JSON → UI displays
[User] → (1) Streamlit → (2) FastAPI → (3) Model objects → (4) Response → [Streamlit] → [User]

##### Architectural patterns & design principles
- Separation of concerns: training vs. inference
- Single-responsibility services: API for inference; Notebook for training; UI for presentation
- Artifact versioning & immutability: pickled models in dedicated directory
- Stateless API: no database, uses files in read-only mode at startup

##### Technologies & libraries
- Python 3.x, FastAPI, Uvicorn (backend)
- Streamlit (frontend)
- scikit-learn, CatBoost, joblib (modeling)
- Pandas, NumPy, SHAP (data processing & interpretability)

##### Detail without overcomplicating
- Do not collapse the inference pipeline—show preprocessing, prediction, clustering as distinct steps

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User
    User["End User (Browser)"]:::external

    %% Offline Training Pipeline
    subgraph "Offline Training Pipeline"
        Notebook["EDA & Training Notebook\nTelco_Customer_Churn.ipynb"]:::compute
        FileStore[(Model Artifact Store\nmodels/)]:::storage
        Notebook -->|"Generates artifacts"| FileStore
    end

    %% Model Artifacts
    FileStore --> Champion["champion_model.pkl v1.0"]:::storage
    FileStore --> Preprocessor["preprocessor.pkl"]:::storage
    FileStore --> Scaler["scaler.pkl"]:::storage
    FileStore --> KMeans["kmeans.pkl"]:::storage

    %% Inference Service
    subgraph "Inference Service"
        API["FastAPI Inference Service\napp.py"]:::compute
        API -->|"loads"| Champion
        API -->|"loads"| Preprocessor
        API -->|"loads"| Scaler
        API -->|"loads"| KMeans
        API -->|"calls Preprocessing"| Preprocess["Preprocessing\n(preprocessor + scaler)"]:::compute
        Preprocess -->|"calls Model"| Predict["Prediction\n(champion_model)"]:::compute
        Predict -->|"calls Clustering"| Cluster["Clustering\n(kmeans)"]:::compute
        Cluster --> API
    end

    %% UI Service
    subgraph "UI Service"
        UI["Streamlit UI\nstreamlit_app.py"]:::compute
        UI -->|"HTTP POST /predict, /segment"| API
        API -->|"JSON response"| UI
        UI --> User
    end

    %% Project Metadata & Config
    Req["requirements.txt"]:::config
    Docs["README.md"]:::config
    GitIgnore[".gitignore"]:::config
    License["LICENSE"]:::config

    %% Connections to Metadata
    Notebook --> Req
    API --> Req
    UI --> Req
    Notebook --> Docs
    API --> Docs
    UI --> Docs

    %% Click Events
    click Notebook "https://github.com/ayushsyntax/telecomchurnprediction/blob/main/Telco_Customer_Churn.ipynb"
    click FileStore "https://github.com/ayushsyntax/telecomchurnprediction/tree/main/models/"
    click Champion "https://github.com/ayushsyntax/telecomchurnprediction/blob/main/models/champion_model.pkl"
    click Preprocessor "https://github.com/ayushsyntax/telecomchurnprediction/blob/main/models/preprocessor.pkl"
    click Scaler "https://github.com/ayushsyntax/telecomchurnprediction/blob/main/models/scaler.pkl"
    click KMeans "https://github.com/ayushsyntax/telecomchurnprediction/blob/main/models/kmeans.pkl"
    click API "https://github.com/ayushsyntax/telecomchurnprediction/blob/main/app.py"
    click UI "https://github.com/ayushsyntax/telecomchurnprediction/blob/main/streamlit_app.py"
    click Req "https://github.com/ayushsyntax/telecomchurnprediction/blob/main/requirements.txt"
    click Docs "https://github.com/ayushsyntax/telecomchurnprediction/blob/main/README.md"
    click GitIgnore "https://github.com/ayushsyntax/telecomchurnprediction/blob/main/.gitignore"
    click License "https://github.com/ayushsyntax/telecomchurnprediction/tree/main/LICENSE"

    %% Styles
    classDef compute fill:#D0E8FF,stroke:#0366d6,stroke-width:2px;
    classDef storage fill:#DFFFE0,stroke:#228B22,stroke-width:2px;
    classDef external fill:#FFE7C0,stroke:#FF8C00,stroke-width:2px;
    classDef config fill:#F0F0F0,stroke:#888888,stroke-width:1px;
```
