# prernajoshipj/customer-churn-prediction architecture

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

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

## Overview

##### Main Components
- User Interface (UI): Represented by the Streamlit frontend in app.py. This component is responsible for collecting user inputs (e.g., tenure, monthly charges) and displaying predictions with visualizations (charts, SHAP plots).
- Machine Learning (ML) Model: The pre-trained XGBoost model (stored as xgb_churn_model.pkl) is the core prediction engine. Note that the project notebook (project.ipynb) contains the process for model training and evaluation.
- Data Source: Include the telecom customer data (Telco_customer_churn.xlsx) which, while not actively queried at runtime, represents the historical data used for model training and evaluation.
- Dependency & Environment Management: The requirements.txt file lists the project dependencies (Pandas, NumPy, Scikit-learn, XGBoost, etc.) and the .devcontainer folder indicates the use of a development container for environment standardization.
- Optional / Supporting Elements: Consider visualizations, SHAP analysis for model explainability, and the possibility of incorporating other future enhancements (e.g., deployment details if moving to Streamlit Cloud).

##### Relationships and Interactions
- User Interaction: The end-user interacts with the Streamlit UI which sends input data to the backend.
- Data Flow: Once the user input is received, the Streamlit app loads the pre-trained XGBoost model and processes the input to generate churn predictions along with feature impact analysis.
- Data Source Connection: Though not directly integrated at runtime, the training data (Telco_customer_churn.xlsx) informs the model and may be referenced as part of the data pipeline in model retraining scenarios.
- Development Environment: The .devcontainer and requirements.txt files suggest a containerized development setup, which is a supporting architecture element.

##### Architectural Patterns & Technologies
- Separation of Concerns: Clearly separate the frontend (user interaction with Streamlit) from the backend (the ML model prediction logic).
- Model Deployment: The deployment of a pre-trained model via on-the-fly input prediction represents a common pattern in ML apps.
- Microservice-Like Structure: Even though the project is contained within a few files, consider the app as having distinct modules—UI, ML processing, and model training—each of which could be evolved independently.

##### Elements
- Clear Labels: Name each component clearly (e.g., “Streamlit Frontend (app.py)”, “XGBoost Prediction Model (xgb_churn_model.pkl)”, “Data Source (Telco_customer_churn.xlsx)”).

- A side component that represents “Model Training & Evaluation (project.ipynb)” that indicates how the model was created and tested using the provided dataset.
- “Data Source (Telco_customer_churn.xlsx)” and indicate its role as the basis for training and evaluation.
- Optionally, include an environment module labeled “Development Container (.devcontainer)” along with “Dependencies (requirements.txt)” to show the overall project context.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["User"]:::user
    B["Streamlit Frontend (app.py)"]:::frontend
    C["ML Engine"]:::backend
    D["XGBoost Prediction Model (xgb_churn_model.pkl)"]:::backend
    E["Predictions & SHAP Visualizations"]:::frontend

    A -->|"submits_input"| B
    B -->|"processes_input"| C
    C -->|"loads_model"| D
    C -->|"returns_results"| E

    subgraph "Project Context"
        F["Model Training & Evaluation (project.ipynb)"]:::training
        G["Data Source (Telco_customer_churn.xlsx)"]:::datasource
        H["Dependencies (requirements.txt)"]:::environment
        I["Development Container (.devcontainer)"]:::environment
    end

    D ---|"trained_with"| F
    G ---|"used_for_training"| F
    B ---|"built_with"| H

    classDef user fill:#ffe0b2,stroke:#bf360c,stroke-width:2px;
    classDef frontend fill:#f8bbd0,stroke:#880e4f,stroke-width:2px;
    classDef backend fill:#c8e6c9,stroke:#1b5e20,stroke-width:2px;
    classDef training fill:#d1c4e9,stroke:#4527a0,stroke-width:2px;
    classDef datasource fill:#ffcc80,stroke:#e65100,stroke-width:2px;
    classDef environment fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;

    click B "https://github.com/prernajoshipj/customer-churn-prediction/blob/main/customer-churn-prediction/app.py"
    click D "https://github.com/prernajoshipj/customer-churn-prediction/blob/main/customer-churn-prediction/xgb_churn_model.pkl"
    click G "https://github.com/prernajoshipj/customer-churn-prediction/blob/main/customer-churn-prediction/Telco_customer_churn.xlsx"
    click F "https://github.com/prernajoshipj/customer-churn-prediction/blob/main/customer-churn-prediction/project.ipynb"
    click H "https://github.com/prernajoshipj/customer-churn-prediction/blob/main/customer-churn-prediction/requirements.txt"
    click I "https://github.com/prernajoshipj/customer-churn-prediction/blob/main/.devcontainer"
```
