# riluck/supply-chain-management-machine-learning architecture

> Architecture diagram of the GitHub repository riluck/supply-chain-management-machine-learning, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/riluck/supply-chain-management-machine-learning
- Repository: https://github.com/riluck/supply-chain-management-machine-learning

## Overview

##### Project type and purpose
- This is a data-science / machine-learning pipeline organized as Jupyter notebooks, aimed at predicting delays in global supply-chain deliveries of essential HIV medicines.
- The workflow reads raw transaction and external index data, cleans and engineers features, explores and selects features, then runs a two-stage “classification then regression” model (delay vs. no-delay, followed by delay-length estimation).

##### File structure
- Top-level artifacts:
- Four sequential notebooks (1–4) implementing data cleaning/feature engineering, EDA/feature selection, model pipeline/benchmarking/refinement, and final modeling/results.
- A helper module (my_helper_functions.py) containing reusable data-processing and modeling routines.
- A Data directory subdivided into:
– Source (raw SCMS CSV/Excel, LPI, FSI, country/continent mappings, Google Maps API results)
– Features (intermediate engineered feature CSVs)
– Results (benchmark and final prediction outputs)
- A README.md and a project report PDF.

##### README for insights
- Inputs: Procurement transaction SCMS data, World Bank LPI, Fund for Peace FSI, Google Maps geocoding.
- Solution: Classification (RandomForest, XGBoost, SVM, etc.) → Regression pipeline.
- Outputs: Performance metrics (Recall, F1, R², RMSE) and result CSVs.
- Environment: Python 3.6.1, Jupyter notebooks, common libraries (pandas, numpy, sklearn, imblearn, yellowbrick, seaborn, matplotlib, googlemaps).

a. Main components
- External Data Sources
– SCMS transaction CSV/Excel files (PEPFAR)
– World Bank LPI data
– Fund for Peace FSI data
– Google Maps Geocoding API
- Data Ingestion & Raw Storage
– Scripts/notebooks that load and standardize these sources into Data/Source
- Data Cleaning & Feature Engineering
– Notebook #1 and helper functions produce Data/Features/*.csv
- Exploratory Data Analysis & Feature Selection
– Notebook #2 uses pandas_profiling, missingno, pivot tables to prune and select features
- Modeling Pipeline
– Notebook #3 orchestrates:
1. Classification model training & benchmark
2. Regression model training on “delayed” subset
– Uses scikit-learn, imblearn, XGBoost, SVM, RandomForest
- Final Model & Results
– Notebook #4 generates final predictions, writes to Data/Results, and creates charts
- Outputs & Reporting
– classifier_benchmark_predicted.csv, classifier_final_predicted.csv, charts, and the capstone report PDF

b. Relationships & data flows
– Flow from Raw Storage → Cleaning/Feature Engine → Features storage
– Flow from Features → EDA/Selection → selected feature set → Modeling Pipeline
– Flow from Modeling → Results storage → Reporting

c. Architectural patterns & principles
– Pipeline pattern: clearly separated ETL (Extract, Transform, Load), analysis, modeling, and reporting stages
– Modularization: reusable helper functions extracted into a separate module
– Two-stage modeling: classification gating followed by regression for prioritized resource allocation

d. Technologies, frameworks & libraries
– Python 3.6.1, Jupyter notebooks
– Data manipulation: pandas, numpy
– Visualization: seaborn, matplotlib, missingno, yellowbrick, pivottablejs
– Modeling: scikit-learn, imblearn, XGBoost, SVM
– External API: googlemaps
– Version control: Git (.gitignore present)

##### Detail but avoid over-fragmentation
- Intermediate storage folders (Source, Features, Results) as persistent nodes.
- Notebook or major script as its own component to illustrate sequence.
- Call out the two-stage classification→regression workflow clearly.
- External inputs (World Bank LPI, FSI, Google Maps API) are individually represented.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data Sources
    subgraph "External Data Sources"
        direction TB
        SCMS["SCMS Raw Data (CSV/Excel)"]:::external
        LPI["World Bank LPI Data"]:::external
        FSI["Fund for Peace FSI Data"]:::external
        GoogleMaps["Google Maps Geocoding API"]:::external
    end

    %% Data Ingestion
    Ingestion["Data Ingestion & Raw Storage"]:::process

    %% Data Cleaning & Feature Engineering
    subgraph "Data Cleaning & Feature Engineering"
        direction TB
        Notebook1["1_Data Cleaning & Feature Engineering.ipynb"]:::notebook
        Helper["my_helper_functions.py"]:::module
        FeaturesStorage["Engineered Features Storage (Data/Features/)"]:::storage
    end

    %% Exploratory Data Analysis & Feature Selection
    subgraph "Exploratory Data Analysis & Feature Selection"
        direction TB
        Notebook2["2_Exploratory Data Analysis & Feature Selection.ipynb"]:::notebook
        SelectedFeatures["Selected Feature Set"]:::data
    end

    %% Modeling Pipeline
    subgraph "Modeling Pipeline"
        direction TB
        Notebook3["3_Model Pipeline, Benchmark, Selection & Refinement.ipynb"]:::notebook
        subgraph "Two-Stage Modeling"
            direction TB
            ClassificationModel["Classification Model"]:::model
            RegressionModel["Regression Model"]:::model
        end
    end

    %% Reporting & Results
    subgraph "Reporting & Results"
        direction TB
        Notebook4["4_Final Model & Results.ipynb"]:::notebook
        ResultsStorage["Prediction Results Storage (Data/Results/)"]:::storage
        ReportDoc["capstone project report.pdf"]:::doc
        Readme["README.md"]:::doc
    end

    %% Flows
    SCMS --> Ingestion
    LPI --> Ingestion
    FSI --> Ingestion
    GoogleMaps --> Ingestion

    Ingestion --> Notebook1
    Notebook1 --> Helper
    Notebook1 --> FeaturesStorage

    FeaturesStorage --> Notebook2
    Notebook2 --> SelectedFeatures

    SelectedFeatures --> Notebook3
    Notebook3 --> ClassificationModel
    ClassificationModel --> RegressionModel
    RegressionModel --> ResultsStorage

    ResultsStorage --> Notebook4
    Notebook4 --> ReportDoc
    Notebook4 --> Readme

    %% Click Events
    click SCMS "https://github.com/riluck/supply-chain-management-machine-learning/tree/master/Data/Source/"
    click LPI "https://github.com/riluck/supply-chain-management-machine-learning/tree/master/Data/Source/"
    click FSI "https://github.com/riluck/supply-chain-management-machine-learning/tree/master/Data/Source/"
    click GoogleMaps "https://github.com/riluck/supply-chain-management-machine-learning/tree/master/Data/Source/"
    click Ingestion "https://github.com/riluck/supply-chain-management-machine-learning/tree/master/Data/Source/"
    click Notebook1 "https://github.com/riluck/supply-chain-management-machine-learning/blob/master/1_Data Cleaning & Feature Engineering.ipynb"
    click Helper "https://github.com/riluck/supply-chain-management-machine-learning/blob/master/my_helper_functions.py"
    click FeaturesStorage "https://github.com/riluck/supply-chain-management-machine-learning/tree/master/Data/Features/"
    click Notebook2 "https://github.com/riluck/supply-chain-management-machine-learning/blob/master/2_Exploratory Data Analysis & Feature Selection.ipynb"
    click Notebook3 "https://github.com/riluck/supply-chain-management-machine-learning/blob/master/3_Model Pipeline, Benchmark, Selection & Refinement.ipynb"
    click Notebook4 "https://github.com/riluck/supply-chain-management-machine-learning/blob/master/4_Final Model & Results.ipynb"
    click ResultsStorage "https://github.com/riluck/supply-chain-management-machine-learning/tree/master/Data/Results/"
    click Readme "https://github.com/riluck/supply-chain-management-machine-learning/blob/master/README.md"
    click ReportDoc "https://github.com/riluck/supply-chain-management-machine-learning/blob/master/capstone project report.pdf"

    %% Styles
    classDef external fill:#E3F2FD,stroke:#1E88E5,color:#0D47A1,stroke-width:1px
    classDef process fill:#E8F5E9,stroke:#43A047,color:#1B5E20,stroke-width:1px
    classDef notebook fill:#FFF3E0,stroke:#FB8C00,color:#E65100,stroke-width:1px
    classDef module fill:#F3E5F5,stroke:#8E24AA,color:#4A148C,stroke-width:1px
    classDef storage fill:#E0F2F1,stroke:#00796B,color:#004D40,stroke-width:1px
    classDef data fill:#FFFDE7,stroke:#FBC02D,color:#F57F17,stroke-width:1px
    classDef model fill:#FFEBEE,stroke:#E53935,color:#B71C1C,stroke-width:1px
    classDef doc fill:#ECEFF1,stroke:#607D8B,color:#263238,stroke-width:1px
```
