# ahmed-m-fayad/customer-churn-prediction-and-analysis architecture

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

- Interactive diagram: https://gitdiagram.com/ahmed-m-fayad/customer-churn-prediction-and-analysis
- Repository: https://github.com/ahmed-m-fayad/customer-churn-prediction-and-analysis

## Overview

##### Project Type and Purpose
- This is an end-to-end machine-learning pipeline for customer-churn prediction.
- It comprises three sequential ETL/ML stages:
a. Data Collection & Preprocessing
b. Advanced Data Analysis & Feature Engineering
c. Model Development & Optimization (including final “complete” deployment pipeline).

##### Main Components & Pipelines
- Raw Data Store
- test.csv, train.csv (in Data Collection/Raw Data)
- Cleaning Pipeline
- cleaning_pipeline.joblib transforms raw → cleaned & imputed CSVs
- Outputs: train_cleaned.csv, train_cleaned_imputed.csv, train_split_cleaned(.csv), validation_split_cleaned.csv
- Feature Engineering Pipeline
- featureEng_encoder_scaler_pipeline.joblib encodes/scales cleaned splits
- Outputs: train_basicFeatureEng.csv, train_split_preprocessed.parquet
- Model Training Pipeline
- complete_churn_pipeline.pkl wraps full preprocessing + model
- custom_transformers.py, feature_pipeline.py define transformations
- best_churn_model_logistic_regression.pkl & xgb_clf_all_features.joblib are final models
- Reports & Notebooks
- Jupyter notebooks record exploratory steps, milestone docs generate PDF/Word reports

##### Relationships & Data Flow
- Cleaned Data Store → Feature Engineering Pipeline → Feature Store
- Feature Store → Model Training Pipeline → Model Artifacts & Deployment Pipeline

##### Architectural Patterns & Design Principles
- Sequential, modular ETL/ML stages (each persists artifacts in joblib/parquet/pkl files)
- Reusability: each pipeline exists as a serialized artifact (joblib/pkl) that can be re-invoked
- Clear separation: data ingestion, transformation, modeling, and reporting

##### Technologies & Frameworks
- Python, pandas, scikit-learn, XGBoost
- joblib for pipeline serialization, parquet for efficient storage
- Jupyter for notebooks, PDF/DOCX for reports

– Input: Raw Data
– Output: cleaned CSVs (list them)
– Input: cleaned splits
– Output: preprocessed parquet & basic feature CSV
– Input: preprocessed data
– Output: final models (.pkl, .joblib)
f. Surrounding: Reports & Notebooks cluster off to the side, linked back to each stage

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Collection & Preprocessing
    subgraph "Data Collection & Preprocessing"
        direction TB
        RawData["Raw Data Store\ntrain.csv, test.csv"]:::dataStore
        CleaningPipeline["Cleaning Pipeline\ncleaning_pipeline.joblib"]:::pipeline
        CleanedData["Cleaned Data Store\ntrain_cleaned.csv, train_cleaned_imputed.csv\ntrain_split_cleaned.csv, train_split_cleaned_imputed.csv, validation_split_cleaned.csv"]:::dataStore
    end

    %% Advanced Data Analysis & Feature Engineering
    subgraph "Advanced Data Analysis & Feature Engineering"
        direction TB
        FeatureEngPipeline["Feature Engineering Pipeline\nfeatureEng_encoder_scaler_pipeline.joblib"]:::pipeline
        FeatureStore["Feature Store\ntrain_basicFeatureEng.csv, train_split_preprocessed.parquet"]:::dataStore
        XGBModel["XGBoost Model\nxgb_clf_all_features.joblib"]:::model
    end

    %% Model Development & Optimization
    subgraph "Model Development & Optimization"
        direction TB
        CompleteChurnPipeline["Complete Churn Pipeline\ncomplete_churn_pipeline.pkl"]:::pipeline
        CustomTransformers["Custom Transformers\ncustom_transformers.py"]:::pipeline
        FeaturePipelineDefs["Feature Pipeline Definitions\nfeature_pipeline.py"]:::pipeline
        LRModel["Logistic Regression Model\nbest_churn_model_logistic_regression.pkl"]:::model
    end

    %% Reports & Notebooks
    subgraph "Reports & Notebooks"
        direction TB
        EDA_Notebook["EDA Notebook\nEDA.ipynb"]:::docs
        Cleaning_Notebook["Cleaning Notebook\ndataCleaning.ipynb"]:::docs
        Analysis_Notebook["Advanced Analysis Notebook\nAdvancedDataAnalysis.ipynb"]:::docs
        FE_Notebook["Feature Engineering Notebook\nFeatureEngineering.ipynb"]:::docs
        Training_Notebook["Model Training Notebook\nmodel_training.ipynb"]:::docs
        EDA_Report["EDA Report\nEDA Report.pdf"]:::docs
        Analysis_Report["Data Analysis Report\nData Analysis Report.pdf"]:::docs
        FE_Report["Feature Engineering Summary\nFeature Engineering Summary.pdf"]:::docs
        ModelDoc1["Model Documentation PDF\nmodel-training-documentation.pdf"]:::docs
        ModelDoc2["Model Documentation DOCX\nmodel_training.docx"]:::docs
        ModelEval["Model Evaluation Report\nmodel_evaluation_report.pkl"]:::docs
    end

    %% Data Flow Connections
    RawData -->|"input to"| CleaningPipeline
    CleaningPipeline -->|"outputs cleaned CSVs"| CleanedData
    CleanedData -->|"input to"| FeatureEngPipeline
    FeatureEngPipeline -->|"outputs features"| FeatureStore
    FeatureStore -->|"input to"| CompleteChurnPipeline
    CompleteChurnPipeline -->|"produces"| LRModel
    CompleteChurnPipeline -->|"produces"| XGBModel

    %% Reports Links
    RawData -->|records in| EDA_Notebook
    CleaningPipeline -->|documents in| Cleaning_Notebook
    FeatureEngPipeline -->|documents in| FE_Notebook
    FeatureEngPipeline -->|analysis in| Analysis_Notebook
    CompleteChurnPipeline -->|notebook| Training_Notebook
    EDA_Notebook -->|report| EDA_Report
    Analysis_Notebook -->|report| Analysis_Report
    FE_Notebook -->|report| FE_Report
    Training_Notebook -->|docs| ModelDoc1
    Training_Notebook -->|docs| ModelDoc2
    Training_Notebook -->|eval| ModelEval

    %% Click Events
    click RawData "https://github.com/ahmed-m-fayad/customer-churn-prediction-and-analysis/tree/main/Data Collection, Exploration, and Preprocessing/Raw Data"
    click CleaningPipeline "https://github.com/ahmed-m-fayad/customer-churn-prediction-and-analysis/blob/main/Data Collection, Exploration, and Preprocessing/pipelines/cleaning_pipeline.joblib"
    click CleanedData "https://github.com/ahmed-m-fayad/customer-churn-prediction-and-analysis/tree/main/Data Collection, Exploration, and Preprocessing/Delivered Data"
    click FeatureEngPipeline "https://github.com/ahmed-m-fayad/customer-churn-prediction-and-analysis/blob/main/Advanced Data Analysis and Feature Engineering/pipelines/featureEng_encoder_scaler_pipeline.joblib"
    click FeatureStore "https://github.com/ahmed-m-fayad/customer-churn-prediction-and-analysis/tree/main/Advanced Data Analysis and Feature Engineering/Delivered Data"
    click CompleteChurnPipeline "https://github.com/ahmed-m-fayad/customer-churn-prediction-and-analysis/blob/main/Machine Learning Model Development and Optimization/Pipeline/complete_churn_pipeline.pkl"
    click CustomTransformers "https://github.com/ahmed-m-fayad/customer-churn-prediction-and-analysis/blob/main/Machine Learning Model Development and Optimization/Modules/custom_transformers.py"
    click FeaturePipelineDefs "https://github.com/ahmed-m-fayad/customer-churn-prediction-and-analysis/blob/main/Machine Learning Model Development and Optimization/Modules/feature_pipeline.py"
    click LRModel "https://github.com/ahmed-m-fayad/customer-churn-prediction-and-analysis/blob/main/Machine Learning Model Development and Optimization/Model/best_churn_model_logistic_regression.pkl"
    click XGBModel "https://github.com/ahmed-m-fayad/customer-churn-prediction-and-analysis/blob/main/Advanced Data Analysis and Feature Engineering/models/xgb_clf_all_features.joblib"
    click EDA_Notebook "https://github.com/ahmed-m-fayad/customer-churn-prediction-and-analysis/blob/main/Data Collection, Exploration, and Preprocessing/Milestone Notebooks/EDA.ipynb"
    click Cleaning_Notebook "https://github.com/ahmed-m-fayad/customer-churn-prediction-and-analysis/blob/main/Data Collection, Exploration, and Preprocessing/Milestone Notebooks/dataCleaning.ipynb"
    click Analysis_Notebook "https://github.com/ahmed-m-fayad/customer-churn-prediction-and-analysis/blob/main/Advanced Data Analysis and Feature Engineering/Milestone Notebooks/AdvancedDataAnalysis.ipynb"
    click FE_Notebook "https://github.com/ahmed-m-fayad/customer-churn-prediction-and-analysis/blob/main/Advanced Data Analysis and Feature Engineering/Milestone Notebooks/FeatureEngineering.ipynb"
    click Training_Notebook "https://github.com/ahmed-m-fayad/customer-churn-prediction-and-analysis/blob/main/Machine Learning Model Development and Optimization/Milestone Notebook/model_training.ipynb"
    click EDA_Report "https://github.com/ahmed-m-fayad/customer-churn-prediction-and-analysis/blob/main/Data Collection, Exploration, and Preprocessing/reports/EDA Report.pdf"
    click Analysis_Report "https://github.com/ahmed-m-fayad/customer-churn-prediction-and-analysis/blob/main/Advanced Data Analysis and Feature Engineering/reports/Data Analysis Report.pdf"
    click FE_Report "https://github.com/ahmed-m-fayad/customer-churn-prediction-and-analysis/blob/main/Advanced Data Analysis and Feature Engineering/reports/Feature Engineering Summary.pdf"
    click ModelDoc1 "https://github.com/ahmed-m-fayad/customer-churn-prediction-and-analysis/blob/main/Machine Learning Model Development and Optimization/Reports/model-training-documentation.pdf"
    click ModelDoc2 "https://github.com/ahmed-m-fayad/customer-churn-prediction-and-analysis/blob/main/Machine Learning Model Development and Optimization/Reports/model_training.docx"
    click ModelEval "https://github.com/ahmed-m-fayad/customer-churn-prediction-and-analysis/blob/main/Machine Learning Model Development and Optimization/Reports/model_evaluation_report.pkl"

    %% Styles
    classDef dataStore fill:#add8e6,stroke:#333,stroke-width:1px
    classDef pipeline fill:#90ee90,stroke:#333,stroke-width:1px
    classDef model fill:#ffa500,stroke:#333,stroke-width:1px
    classDef docs fill:#d3d3d3,stroke:#333,stroke-width:1px
```
