# mukund-1/churn-modelling architecture

> Architecture diagram of the GitHub repository mukund-1/churn-modelling, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mukund-1/churn-modelling
- Repository: https://github.com/mukund-1/churn-modelling

## Overview

##### Project type and purpose
- This is a single‐page Streamlit web application for real‐time customer churn prediction at a bank.
- It loads a pre‐trained TensorFlow deep learning model and associated preprocessing artifacts (encoders and scaler) to predict churn probability based on user‐provided inputs.

##### File structure
- Top‐level files:
- app.py  – Streamlit app (serving logic + UI)
- model.h5  – pre‐trained TensorFlow model
- onehot_encoder_geo.pkl, label_encoder_gender.pkl, scaler.pkl  – preprocessing artifacts
- Churn_Modelling.csv  – raw dataset used during training
- experiments.ipynb, hyperparametertuningann.ipynb, prediction.ipynb  – Jupyter notebooks for data exploration, model tuning, prediction experiments
- requirements.txt  – Python dependencies list
- There is no separate “frontend” and “backend” directory; the Streamlit script combines both layers.

##### Extract key insights from the README
- Inputs: Geography, Gender, Age, Balance, Credit Score, Estimated Salary, Tenure, Number of Products, Credit Card flag, Active Membership flag
- Preprocessing: label encoding, one‐hot encoding, feature scaling
- Prediction threshold: 0.5
- Run command: `streamlit run app.py`

##### Main components
a. User Interface (UI)
– Streamlit web front end (dropdowns, sliders, input fields)
– Hosted by Streamlit server
b. Serving/Inference Pipeline
– app.py (requests → preprocessing → model inference → response)
– Preprocessing module
- LabelEncoder (gender)
- OneHotEncoder (geography)
- Scaler
– Model module
- TensorFlow model.h5
c. Data Artifacts & Repositories
– model repository (model.h5, *.pkl files)
– raw data CSV (Churn_Modelling.csv) used in training
– Jupyter notebooks (experiments & hyperparameter tuning)
d. Dependencies & Environment
– Python runtime
– Libraries: streamlit, tensorflow, scikit‐learn, pandas, numpy, etc.

##### Relationships and interactions
- User interacts with Streamlit UI → UI sends input payload to app.py
- app.py loads preprocessing artifacts → transforms raw inputs into model‐ready feature vector
- Preprocessed data flows into TensorFlow model → churn probability returned
- app.py applies decision threshold → output (“likely to churn” / “unlikely to churn”) displayed back on the UI
- The raw dataset and notebooks feed into an offline training pipeline (not part of the runtime app) that produces the model and artifacts.

##### Important architectural patterns/design principles
- Separation of concerns:
- UI layer (Streamlit)
- Preprocessing layer (encoders + scaler)
- Model inference layer (TensorFlow)
- Immutable artifacts: model.h5 and pickles are read‐only in production
- Lightweight one‐service architecture: all components run in a single Python process under Streamlit

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and UI
    User["User"]:::external
    StreamlitUI["Streamlit UI"]:::ui
    User -->|"interacts with"| StreamlitUI

    %% Serving Environment
    subgraph "Serving Environment"
        PythonEnv["Python Environment"]:::compute
        StreamlitUI
        subgraph "Preprocessing Module"
            GenderEncoder["LabelEncoder (gender)"]:::data
            GeoEncoder["OneHotEncoder (geography)"]:::data
            Scaler["Feature Scaler"]:::data
        end
        TFModel["TensorFlow Model"]:::data
        Decision["Decision Threshold (0.5)"]:::compute
    end

    %% Artifact Store
    subgraph "Artifact Store"
        GenderEncoder
        GeoEncoder
        Scaler
        TFModel
    end

    %% Offline Training Pipeline
    subgraph "Offline Training Pipeline"
        RawData["Churn_Modelling.csv"]:::offline
        Experiments["experiments.ipynb"]:::offline
        HyperTune["hyperparametertuningann.ipynb"]:::offline
        PredictionNB["prediction.ipynb"]:::offline
    end

    %% Dependencies
    Requirements["requirements.txt"]:::data

    %% Data Flow
    StreamlitUI -->|"raw inputs"| GenderEncoder
    GenderEncoder -->|"encoded gender"| PreprocessingModule0[ ] 
    StreamlitUI -->|"raw inputs"| GeoEncoder
    GeoEncoder -->|"one-hot features"| PreprocessingModule0
    StreamlitUI -->|"raw inputs"| Scaler
    Scaler -->|"scaled features"| PreprocessingModule0
    PreprocessingModule0 -->|"feature vector"| TFModel
    TFModel -->|"churn probability"| Decision
    Decision -->|"prediction output"| StreamlitUI
    StreamlitUI -->|"displays result"| User

    %% Offline Flow
    RawData -->|"used in"| Experiments
    RawData -->|"used in"| HyperTune
    RawData -->|"used in"| PredictionNB
    Experiments -->|"produces artifacts"| ArtifactStore0[ ]
    HyperTune -->|"produces artifacts"| ArtifactStore0
    PredictionNB -->|"produces artifacts"| ArtifactStore0

    %% Dependencies link
    PythonEnv -->|"installs"| Requirements

    %% Click Events
    click StreamlitUI "https://github.com/mukund-1/churn-modelling/blob/main/app.py"
    click GenderEncoder "https://github.com/mukund-1/churn-modelling/blob/main/label_encoder_gender.pkl"
    click GeoEncoder "https://github.com/mukund-1/churn-modelling/blob/main/onehot_encoder_geo.pkl"
    click Scaler "https://github.com/mukund-1/churn-modelling/blob/main/scaler.pkl"
    click TFModel "https://github.com/mukund-1/churn-modelling/blob/main/model.h5"
    click RawData "https://github.com/mukund-1/churn-modelling/blob/main/Churn_Modelling.csv"
    click Experiments "https://github.com/mukund-1/churn-modelling/blob/main/experiments.ipynb"
    click HyperTune "https://github.com/mukund-1/churn-modelling/blob/main/hyperparametertuningann.ipynb"
    click PredictionNB "https://github.com/mukund-1/churn-modelling/blob/main/prediction.ipynb"
    click Requirements "https://github.com/mukund-1/churn-modelling/blob/main/requirements.txt"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085;
    classDef compute fill:#d4edda,stroke:#155724,color:#155724;
    classDef data fill:#fff3cd,stroke:#856404,color:#856404;
    classDef offline fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24;
```
