# krish-kunjadiya/supplychain_forecasting_and_optimization architecture

> Architecture diagram of the GitHub repository krish-kunjadiya/supplychain_forecasting_and_optimization, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/krish-kunjadiya/supplychain_forecasting_and_optimization
- Repository: https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization

## Overview

1. This repository is an offline, notebook-orchestrated analytics pipeline rather than a deployed application. The architecture is a linear sequence of 8 Jupyter notebooks that transform raw supply-chain data into forecasts, inventory policies, and a stakeholder-facing dashboard.

2. The primary boundary is the input dataset in `data/supply_chain_dataset1.csv`, which is intentionally excluded from version control. Everything else in the repo is either a derived artifact, a trained model, a metrics file, or a visualization output.

3. Notebook 01 performs data loading, cleaning, validation, missing-value handling, and type/range checks. Its output, `supply_chain_validated.csv`, becomes the trusted base dataset for the rest of the pipeline.

4. Notebook 02 is the exploratory analysis layer. It reshapes the validated data into `supply_chain_eda_ready.csv` and is the point where descriptive statistics, seasonality inspection, and feature relationships are established before modeling.

5. Notebook 03 is the feature engineering boundary between analysis and modeling. It produces two model-specific datasets: `features_lstm.csv` for sequence modeling and `features_xgboost.csv` for tabular learning, plus `feature_registry.json` to document the engineered feature set and transformation metadata.

6. The forecasting layer splits into two parallel model tracks. Notebook 04 trains the LSTM time-series model and persists TensorFlow/Keras artifacts (`lstm_best_model.keras`, `lstm_final_model.keras`) plus evaluation outputs. Notebook 05 trains the XGBoost model, saving tuned parameters, the final model, feature importance outputs, and test predictions. This is the main modeling fork in the architecture.

7. Notebook 06 is the ensemble integration layer. It consumes LSTM and XGBoost predictions and compares multiple blending strategies: simple average, weighted blend, meta-learner stacking, and per-SKU dynamic weighting. The outputs include `hybrid_predictions.csv`, `hybrid_metrics.json`, `all_model_comparison.csv`, and `sku_dynamic_weights.csv`.

8. Notebook 07 converts forecasts into operational decisions. It uses the selected/hybrid demand forecasts to calculate reorder points, EOQ, and safety stock, then simulates policy performance and quantifies business impact. This stage produces `inventory_policy.csv`, `policy_comparison.csv`, `simulation_results.csv`, and `business_value.json`.

9. Notebook 08 is the presentation and reporting layer. It aggregates model metrics, inventory outcomes, and business value into seven static chart images and a self-contained `supply_chain_dashboard.html` report. This is the final consumable artifact for stakeholders.

10. The repo’s persisted artifacts form a clear data lineage: raw data → validated data → EDA-ready data → engineered features → model outputs → ensemble outputs → inventory policy → dashboard/report. The JSON, CSV, Keras, PKL, and HTML files are all checkpoints in that lineage rather than independent products.

11. The main technologies that materially shape the architecture are Python notebooks, pandas/numpy for data processing, scikit-learn for preprocessing and metrics, TensorFlow/Keras for LSTM training, XGBoost for gradient-boosted forecasting, and matplotlib/seaborn for reporting. The optional LightGBM meta-learner appears only within the hybrid notebook.

12. Conceptually, the system has three important layers: data preparation, predictive modeling, and decision optimization. The final business value comes from connecting forecast accuracy to inventory policy simulation, not from forecasting alone.

Main entry points: [`08_results_dashboard.ipynb`](https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/08_results_dashboard.ipynb) (08 Dashboard), [`03_feature_engineering.ipynb`](https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/03_feature_engineering.ipynb) (03 Features), [`04_lstm_model.ipynb`](https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/04_lstm_model.ipynb) (04 LSTM), [`05_xgboost_model.ipynb`](https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/05_xgboost_model.ipynb) (05 XGBoost)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Data prep"]
  node_raw_data[("Raw data<br/>input dataset")]
  node_nb01["01 Validate<br/>notebook"]
  node_validated[("Validated data<br/>trusted dataset")]
  node_nb02["02 EDA<br/>notebook<br/>[02_eda.ipynb]"]
  node_eda_ready[("EDA-ready data<br/>analysis dataset")]
  node_nb03["03 Features<br/>notebook"]
  node_features_lstm[("LSTM features<br/>sequence data")]
  node_features_xgb[("XGB features<br/>tabular data")]
  node_feature_registry["Feature registry<br/>metadata"]
end

subgraph group_forecast["Forecasting"]
  node_nb04["04 LSTM<br/>notebook"]
  node_lstm_model(("LSTM model<br/>keras artifacts"))
  node_lstm_metrics["LSTM metrics<br/>evaluation<br/>[lstm_metrics.json]"]
  node_lstm_scaler["LSTM scaler<br/>preprocessor<br/>[lstm_scaler.pkl]"]
  node_nb05["05 XGBoost<br/>notebook"]
  node_xgb_model(("XGB model<br/>booster model"))
  node_xgb_params["Best params<br/>tuning metadata"]
  node_xgb_metrics["XGB metrics<br/>evaluation<br/>[xgb_metrics.json]"]
  node_nb06["06 Hybrid<br/>notebook"]
  node_hybrid_outputs["Hybrid outputs<br/>ensemble outputs"]
end

subgraph group_optimize["Optimization"]
  node_nb07["07 Inventory<br/>notebook"]
  node_policy_outputs["Policy outputs<br/>inventory analytics"]
end

subgraph group_report["Reporting"]
  node_nb08["08 Dashboard<br/>notebook"]
  node_dashboard["Dashboard<br/>report"]
end

node_raw_data -->|"source data"| node_nb01
node_nb01 -->|"writes"| node_validated
node_validated -->|"input"| node_nb02
node_nb02 -->|"writes"| node_eda_ready
node_eda_ready -->|"input"| node_nb03
node_nb03 -->|"writes"| node_features_lstm
node_nb03 -->|"writes"| node_features_xgb
node_nb03 -->|"documents"| node_feature_registry
node_features_lstm -->|"input"| node_nb04
node_nb04 -->|"persists"| node_lstm_model
node_nb04 -->|"evaluates"| node_lstm_metrics
node_nb04 -->|"persists"| node_lstm_scaler
node_features_xgb -->|"input"| node_nb05
node_nb05 -->|"writes"| node_xgb_params
node_nb05 -->|"persists"| node_xgb_model
node_nb05 -->|"evaluates"| node_xgb_metrics
node_lstm_model -->|"forecast input"| node_nb06
node_xgb_model -->|"forecast input"| node_nb06
node_nb06 -->|"writes"| node_hybrid_outputs
node_hybrid_outputs -->|"selected forecast"| node_nb07
node_nb07 -->|"writes"| node_policy_outputs
node_policy_outputs -->|"input"| node_nb08
node_lstm_metrics -->|"input"| node_nb08
node_xgb_metrics -->|"input"| node_nb08
node_hybrid_outputs -->|"input"| node_nb08
node_nb08 -->|"writes"| node_dashboard

click node_nb01 "https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/01_data_loading_and_validation.ipynb"
click node_nb02 "https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/02_eda.ipynb"
click node_nb03 "https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/03_feature_engineering.ipynb"
click node_feature_registry "https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/feature_registry.json"
click node_nb04 "https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/04_lstm_model.ipynb"
click node_lstm_model "https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/lstm_final_model.keras"
click node_lstm_metrics "https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/lstm_metrics.json"
click node_lstm_scaler "https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/lstm_scaler.pkl"
click node_nb05 "https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/05_xgboost_model.ipynb"
click node_xgb_model "https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/xgb_final_model.pkl"
click node_xgb_params "https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/xgb_best_params.json"
click node_xgb_metrics "https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/xgb_metrics.json"
click node_nb06 "https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/06_hybrid_model.ipynb"
click node_hybrid_outputs "https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/hybrid_metrics.json"
click node_nb07 "https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/07_inventory_optimization.ipynb"
click node_policy_outputs "https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/business_value.json"
click node_nb08 "https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/08_results_dashboard.ipynb"
click node_dashboard "https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/supply_chain_dashboard.html"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_raw_data,node_nb01,node_validated,node_nb02,node_eda_ready,node_nb03,node_features_lstm,node_features_xgb,node_feature_registry toneBlue
class node_nb04,node_lstm_model,node_lstm_metrics,node_lstm_scaler,node_nb05,node_xgb_model,node_xgb_params,node_xgb_metrics,node_nb06,node_hybrid_outputs toneAmber
class node_nb07,node_policy_outputs toneMint
class node_nb08,node_dashboard toneRose
```

## Components

### Data prep

Raw data boundary, validation, EDA, and feature engineering.

- **Raw data**: input dataset · Excluded source CSV boundary for the pipeline.
- [01 Validate](https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/01_data_loading_and_validation.ipynb): notebook · Loads, cleans, validates, and standardizes the source data. · `01_data_loading_and_validation.ipynb`
- **Validated data**: trusted dataset · Cleaned base dataset used by the rest of the pipeline.
- [02 EDA](https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/02_eda.ipynb): notebook · Exploratory analysis, descriptive statistics, and feature inspection. · `02_eda.ipynb`
- **EDA-ready data**: analysis dataset · Reshaped dataset prepared for feature engineering.
- [03 Features](https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/03_feature_engineering.ipynb): notebook · Builds model-specific features and records feature metadata. · `03_feature_engineering.ipynb`
- **LSTM features**: sequence data · Engineered sequence features for time-series forecasting.
- **XGB features**: tabular data · Engineered tabular features for gradient-boosted forecasting.
- [Feature registry](https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/feature_registry.json): metadata · Feature definitions and transformation metadata. · `feature_registry.json`

### Forecasting

Parallel model tracks and ensemble integration.

- [04 LSTM](https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/04_lstm_model.ipynb): notebook · Trains the Keras time-series model and evaluates forecasts. · `04_lstm_model.ipynb`
- [LSTM model](https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/lstm_final_model.keras): keras artifacts · Persisted best and final LSTM models. · `lstm_final_model.keras`
- [LSTM metrics](https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/lstm_metrics.json): evaluation · Model evaluation outputs for the LSTM track. · `lstm_metrics.json`
- [LSTM scaler](https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/lstm_scaler.pkl): preprocessor · Scaling artifact used with the LSTM workflow. · `lstm_scaler.pkl`
- [05 XGBoost](https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/05_xgboost_model.ipynb): notebook · Trains the XGBoost forecasting model and captures tuning results. · `05_xgboost_model.ipynb`
- [XGB model](https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/xgb_final_model.pkl): booster model · Final trained XGBoost predictor. · `xgb_final_model.pkl`
- [Best params](https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/xgb_best_params.json): tuning metadata · Selected XGBoost hyperparameters. · `xgb_best_params.json`
- [XGB metrics](https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/xgb_metrics.json): evaluation · XGBoost tuning, importance, and test-set metrics. · `xgb_metrics.json`
- [06 Hybrid](https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/06_hybrid_model.ipynb): notebook · Blends model forecasts with averaging, stacking, and dynamic weighting. · `06_hybrid_model.ipynb`
- [Hybrid outputs](https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/hybrid_metrics.json): ensemble outputs · Blended forecasts, comparisons, and meta-model artifacts. · `hybrid_metrics.json`

### Optimization

Forecasts turned into inventory decisions and business impact.

- [07 Inventory](https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/07_inventory_optimization.ipynb): notebook · Turns forecasts into reorder points, EOQ, safety stock, and simulations. · `07_inventory_optimization.ipynb`
- [Policy outputs](https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/business_value.json): inventory analytics · Inventory policy, comparisons, simulations, and business value. · `business_value.json`

### Reporting

Dashboard assembly and stakeholder-facing outputs.

- [08 Dashboard](https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/08_results_dashboard.ipynb): notebook · Assembles charts and the final stakeholder report. · `08_results_dashboard.ipynb`
- [Dashboard](https://github.com/krish-kunjadiya/supplychain_forecasting_and_optimization/blob/main/supply_chain_dashboard.html): report · Self-contained HTML summary of results and charts. · `supply_chain_dashboard.html`

## Connections

- Raw data → 01 Validate: source data · Notebook 01 ingests the raw CSV boundary.
- 01 Validate → Validated data: writes · Validated dataset becomes the trusted base.
- Validated data → 02 EDA: input · EDA starts from the validated dataset.
- 02 EDA → EDA-ready data: writes · Produces EDA-ready reshaped data.
- EDA-ready data → 03 Features: input · Feature engineering builds on analysis output.
- 03 Features → LSTM features: writes · Creates sequence features for LSTM training.
- 03 Features → XGB features: writes · Creates tabular features for XGBoost training.
- 03 Features → Feature registry: documents · Records engineered feature definitions and lineage.
- LSTM features → 04 LSTM: input · LSTM training consumes sequence features.
- 04 LSTM → LSTM model: persists · Stores best and final Keras model artifacts.
- 04 LSTM → LSTM metrics: evaluates · Outputs forecast accuracy and diagnostics.
- 04 LSTM → LSTM scaler: persists · Stores scaling state used by the LSTM workflow.
- XGB features → 05 XGBoost: input · XGBoost training consumes tabular features.
- 05 XGBoost → Best params: writes · Persists the tuned parameter set.
- 05 XGBoost → XGB model: persists · Stores the final boosted-tree model.
- 05 XGBoost → XGB metrics: evaluates · Outputs tuning and test-set metrics.
- LSTM model → 06 Hybrid: forecast input · Hybrid layer consumes LSTM predictions.
- XGB model → 06 Hybrid: forecast input · Hybrid layer consumes XGBoost predictions.
- 06 Hybrid → Hybrid outputs: writes · Produces blended forecasts and ensemble comparisons.
- Hybrid outputs → 07 Inventory: selected forecast · Inventory optimization uses the chosen hybrid demand signal.
- 07 Inventory → Policy outputs: writes · Generates policy, simulation, and business impact artifacts.
- Policy outputs → 08 Dashboard: input · Reporting aggregates inventory outcomes and value.
- LSTM metrics → 08 Dashboard: input · Dashboard includes model evaluation summaries.
- XGB metrics → 08 Dashboard: input · Dashboard includes model evaluation summaries.
- Hybrid outputs → 08 Dashboard: input · Dashboard includes ensemble comparison results.
- 08 Dashboard → Dashboard: writes · Final stakeholder-facing HTML report.
