# true-star-580/dsc_phase_3_project architecture

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

- Interactive diagram: https://gitdiagram.com/true-star-580/dsc_phase_3_project
- Repository: https://github.com/true-star-580/dsc_phase_3_project

## Overview

##### Project Type and Purpose
- This is a data‐science/ML pipeline for customer churn prediction. It ingests raw customer data (CSV), performs EDA and preprocessing in Jupyter, trains and evaluates multiple classifiers, selects an optimized XGBoost model, serializes it to disk, and produces outputs (model file, presentations).
- The goal is to predict individual churn risk and enable targeted retention workflows.

##### Main Components
a. Data Source
- bigml_59c28831336c6604c800002a.csv (raw customer records)
b. Data Processing & EDA
- index.ipynb notebook: exploratory analysis, cleaning, feature engineering, imbalance handling (SMOTE)
c. Model Training & Evaluation
- index.ipynb: dummy, logistic, decision tree, GBM, XGBoost models; cross‐validation; hyperparameter tuning
d. Model Artifacts
- xgb_model.pkl (serialized XGBoost model)
e. Reporting & Presentation
- Non-technical Presentation.pdf
- Presentation_Paul Kamau.pdf
- README.md documentation

##### Relationships and Data Flow
- Raw CSV → EDA Notebook → Cleaned/Engineered Dataset → Model Training → Evaluation Metrics → Best Model Selection → Serialization (xgb_model.pkl) → Reporting Dashboards/Presentations.

##### Architectural Patterns & Principles
- Modular Pipeline: clear separation of ingestion, cleaning, modeling, and reporting stages.
- Reproducibility: Use notebooks to capture analysis steps; serialize model for deployment.
- Artifact Management: CSV and pickle file are versioned inputs/outputs.
- Scalability Concern (future): swap CSV for data warehouse or streaming source; wrap notebook steps in scripts or workflow orchestrator.

##### Technologies & Libraries
- Jupyter Notebook (index.ipynb) for orchestration of steps
- Python data stack: pandas, numpy, scikit-learn, imbalanced‐learn (SMOTE)
- XGBoost library for final model
- Pickle for model persistence
- Reporting via PDF exports or future dashboard (e.g., Streamlit, Dash)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion
    A["bigml_59c28831336c6604c800002a.csv"]:::data
    click A "https://github.com/true-star-580/dsc_phase_3_project/blob/main/bigml_59c28831336c6604c800002a.csv"

    %% Processing Stage
    subgraph "Data Processing & EDA" 
        direction TB
        B["index.ipynb\n(EDA & Preprocessing)"]:::process
    end
    click B "https://github.com/true-star-580/dsc_phase_3_project/blob/main/index.ipynb"

    A -->|"raw data ingestion"| B

    %% Training Stage
    subgraph "Model Training & Evaluation"
        direction TB
        C["index.ipynb\n(Model Training & Evaluation)"]:::model
        C1["Tested Models:\nDummy, Logistic,\nDecision Tree,\nGBM, XGBoost"]:::model
    end
    click C "https://github.com/true-star-580/dsc_phase_3_project/blob/main/index.ipynb"
    
    B -->|"cleaned dataset"| C
    C -->|"evaluation metrics"| C1

    %% Model Artifact
    D["xgb_model.pkl\n(93.5% Acc,\n89% Prec,\n76% Rec)"]:::artifact
    click D "https://github.com/true-star-580/dsc_phase_3_project/blob/main/xgb_model.pkl"
    C1 -->|"best model selection & serialization"| D

    %% Reporting & Presentation
    subgraph "Reporting & Presentation"
        direction TB
        E["Non-technical Presentation.pdf"]:::output
        F["Presentation_Paul Kamau.pdf"]:::output
        G["README.md"]:::output
    end
    click E "https://github.com/true-star-580/dsc_phase_3_project/blob/main/Non-technical Presentation.pdf"
    click F "https://github.com/true-star-580/dsc_phase_3_project/blob/main/Presentation_Paul Kamau.pdf"
    click G "https://github.com/true-star-580/dsc_phase_3_project/blob/main/README.md"

    D -->|"model output"| E
    D -->|"model output"| F
    D -->|"documentation"| G

    %% Versioning
    H[".ipynb_checkpoints/"]:::version
    click H "https://github.com/true-star-580/dsc_phase_3_project/tree/main/.ipynb_checkpoints/"
    B -->|"notebook versions"| H
    C -->|"notebook versions"| H

    %% Future Deployment
    I["Future: Model Deployment API"]:::future
    D -->|"serve model"| I

    %% Legend
    subgraph "Legend"
        direction TB
        L1["CSV Data Source"]:::data
        L2["Processing Step"]:::process
        L3["Modeling Step"]:::model
        L4["Artifact / Output"]:::artifact
        L5["Report / Documentation"]:::output
        L6["Version Control"]:::version
        L7["Future Component"]:::future
    end

    classDef data fill:#cce5ff,stroke:#004085,color:#004085;
    classDef process fill:#d4edda,stroke:#155724,color:#155724;
    classDef model fill:#ffe5b4,stroke:#b35f00,color:#b35f00;
    classDef artifact fill:#e2d6f3,stroke:#512a60,color:#512a60;
    classDef output fill:#f5c6cb,stroke:#721c24,color:#721c24;
    classDef version fill:#fdfd96,stroke:#9c6500,color:#9c6500;
    classDef future fill:#d6d8d9,stroke:#1b1e21,color:#1b1e21;
```
