# dhavaldalvi/customer-churn-prediction architecture

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

- Interactive diagram: https://gitdiagram.com/dhavaldalvi/customer-churn-prediction
- Repository: https://github.com/dhavaldalvi/customer-churn-prediction

## Overview

##### Project type and purpose
- This is a full-stack web application (Flask) whose primary purpose is to predict customer churn using machine learning.
- The README confirms it provides a web UI for users to input customer features, runs a ML model pipeline, and returns a churn probability.

##### File structure
- Top level:
- app.py – Flask application entry point with routes for “home” and “result.”
- setup.py, requirements.txt – packaging and dependencies.
- artifacts/, data/ – local file-system stores for raw, train, test CSVs and model outputs.
- notebook/ – exploratory analysis and training notebooks (offline).
- src/customer_churn_prediction:
- components/
– data_ingestion.py
– data_transformation.py
– model_trainer.py
- pipelines/
– training_pipeline.py
– prediction_pipeline.py
- config.py, exception.py, logger.py, utils.py
- templates/ + static/ – HTML/CSS UI layers.

##### README for additional insights
- Confirms use of Flask, Scikit-learn, Pandas, NumPy.
- Explains that on startup the app runs model training to select the best model, then serves the web UI.

a. Main components:
1. User & Browser (Frontend)
2. Flask Web Server (app.py/routes)
3. Templates & Static assets (UI layer)
4. Prediction Pipeline (src/.../prediction_pipeline.py)
5. Training Pipeline (src/.../training_pipeline.py) – runs at startup
6. Components Layer:
– Data Ingestion
– Data Transformation
– Model Trainer
7. File-System Data Store:
– artifacts/raw_data.csv
– artifacts/train_data.csv
– artifacts/test_data.csv
– model artifact (.pkl)
b. Relationships & interactions:
- User → Browser → HTTP request to Flask route (GET home.html / POST form data)
- Flask route invokes Prediction Pipeline
- Prediction Pipeline calls Data Ingestion (loads CSV or form payload), Data Transformation (feature engineering), loads persisted model from artifacts, returns prediction
- Flask returns result.html populated with churn probability
- On startup, Flask app invokes Training Pipeline which:
- Ingests raw data from data/Churn_Modelling.csv or artifacts/raw_data.csv
- Transforms data
- Trains multiple models via Model Trainer
- Selects best model and writes .pkl to artifacts
c. Architectural patterns & principles
- Layered architecture:
- Presentation (Flask + Jinja templates + static CSS)
- Application (Flask controllers + pipelines)
- Domain/Service (components: ingestion, transformation, training)
- Infrastructure (file-system storage of CSVs and model artifacts)
- Single-responsibility per component, separation of concerns.
d. Technologies/frameworks:
- Flask (web layer)
- Scikit-learn (model training & inference)
- Pandas & NumPy (data handling)
- Jinja2 (templating)
- Plain CSV files as storage

##### Elements
- From User to Browser to Flask (GET/POST)
- From Flask to Prediction Pipeline to Components to Artifacts to Flask to Browser
- From Flask on startup to Training Pipeline to Components to Artifacts
- Blue for “Frontend/UI”
- Green for “Backend/Application”
- Yellow for “Service/Domain Components”
- Gray for “Storage/Artifacts”

##### Final advice
- Be very detailed: capture both the one‐time training flow and the recurring prediction flow.
- Avoid over-abstraction: instead of a single “ML Service,” expose Data Ingestion, Transformation, Trainer modules to show the responsibilities clearly.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        User["User"]:::external
        Browser["Browser"]:::external
        Home["Home Page"]:::frontend
        Result["Result Page"]:::frontend
        CSS["CSS Styles"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        Flask["Flask Web Server"]:::backend
        Config["Core Configuration"]:::backend
        Exception["Exception Handling"]:::backend
        Logger["Logging Utility"]:::backend
        Utils["General Utilities"]:::backend
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        PredPipe["Prediction Pipeline"]:::service
        TrainPipe["Training Pipeline"]:::service
        Ingest["Data Ingestion"]:::service
        Transform["Data Transformation"]:::service
        Trainer["Model Trainer"]:::service
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        RawSource["Raw Data Source\n(data/Churn_Modelling.csv)"]:::storage
        RawSplit["artifacts/raw_data.csv"]:::storage
        TrainSplit["artifacts/train_data.csv"]:::storage
        TestSplit["artifacts/test_data.csv"]:::storage
        ModelArtifact["artifacts/<model_name>.pkl"]:::storage
    end

    %% Relationships
    User -->|uses| Browser
    Browser -->|HTTP GET home| Flask
    Flask -->|renders| Home
    Home -->|loads CSS| CSS
    Browser -->|submits form POST| Flask
    Flask -->|invokes| PredPipe
    PredPipe -->|uses| Ingest
    PredPipe -->|uses| Transform
    PredPipe -->|loads model| ModelArtifact
    PredPipe -->|returns prediction| Flask
    Flask -->|renders| Result
    Flask -->|serves| CSS
    Result -->|displays| Browser

    %% Startup Training Flow
    Flask -->|on startup invokes| TrainPipe
    TrainPipe -->|ingests raw| RawSource
    TrainPipe -->|writes split| RawSplit
    TrainPipe -->|writes split| TrainSplit
    TrainPipe -->|writes split| TestSplit
    TrainPipe -->|trains models| Trainer
    Trainer -->|writes model| ModelArtifact

    %% Misc Dependencies
    PredPipe -->|reads| Config
    TrainPipe -->|reads| Config
    PredPipe -->|handles errors with| Exception
    TrainPipe -->|handles errors with| Exception
    PredPipe -->|logs via| Logger
    TrainPipe -->|logs via| Logger
    PredPipe -->|utils| Utils
    TrainPipe -->|utils| Utils

    %% Click Events
    click Flask "https://github.com/dhavaldalvi/customer-churn-prediction/blob/main/app.py"
    click Home "https://github.com/dhavaldalvi/customer-churn-prediction/blob/main/templates/home.html"
    click Result "https://github.com/dhavaldalvi/customer-churn-prediction/blob/main/templates/result.html"
    click CSS "https://github.com/dhavaldalvi/customer-churn-prediction/blob/main/static/style.css"
    click PredPipe "https://github.com/dhavaldalvi/customer-churn-prediction/blob/main/src/customer_churn_prediction/pipelines/prediction_pipeline.py"
    click TrainPipe "https://github.com/dhavaldalvi/customer-churn-prediction/blob/main/src/customer_churn_prediction/pipelines/training_pipeline.py"
    click Ingest "https://github.com/dhavaldalvi/customer-churn-prediction/blob/main/src/customer_churn_prediction/components/data_ingestion.py"
    click Transform "https://github.com/dhavaldalvi/customer-churn-prediction/blob/main/src/customer_churn_prediction/components/data_transformation.py"
    click Trainer "https://github.com/dhavaldalvi/customer-churn-prediction/blob/main/src/customer_churn_prediction/components/model_trainer.py"
    click Config "https://github.com/dhavaldalvi/customer-churn-prediction/blob/main/src/customer_churn_prediction/config.py"
    click Exception "https://github.com/dhavaldalvi/customer-churn-prediction/blob/main/src/customer_churn_prediction/exception.py"
    click Logger "https://github.com/dhavaldalvi/customer-churn-prediction/blob/main/src/customer_churn_prediction/logger.py"
    click Utils "https://github.com/dhavaldalvi/customer-churn-prediction/blob/main/src/customer_churn_prediction/utils.py"
    click RawSource "https://github.com/dhavaldalvi/customer-churn-prediction/blob/main/data/Churn_Modelling.csv"
    click RawSplit "https://github.com/dhavaldalvi/customer-churn-prediction/blob/main/artifacts/raw_data.csv"
    click TrainSplit "https://github.com/dhavaldalvi/customer-churn-prediction/blob/main/artifacts/train_data.csv"
    click TestSplit "https://github.com/dhavaldalvi/customer-churn-prediction/blob/main/artifacts/test_data.csv"
    click ModelArtifact "https://github.com/dhavaldalvi/customer-churn-prediction/blob/main/artifacts/<model_name>.pkl"

    %% Styles
    classDef frontend fill:#add8e6,stroke:#000,stroke-width:1px
    classDef backend fill:#90ee90,stroke:#000,stroke-width:1px
    classDef service fill:#ffff99,stroke:#000,stroke-width:1px
    classDef storage fill:#d3d3d3,stroke:#000,stroke-width:1px
    classDef external fill:#f0f0f0,stroke:#000,stroke-width:1px
```
