# kbajish/ai-supply-chain-forecasting architecture

> Architecture diagram of the GitHub repository kbajish/ai-supply-chain-forecasting, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kbajish/ai-supply-chain-forecasting
- Repository: https://github.com/kbajish/ai-supply-chain-forecasting

## Overview

1. This repository is a two-part ML application with a shared core library: a FastAPI backend in `api/` and a Streamlit dashboard in `dashboard/`, both consuming model and inference code from `src/`. The project is organized around an offline training pipeline that produces artifacts, and an online serving layer that reads those artifacts to answer forecast, risk, and narrative requests.

2. The data subsystem lives in `src/data/`. `generator.py` creates the synthetic industrial supply chain datasets: daily demand series for SKUs and separate supplier risk records. `preprocess.py` turns raw demand into model-ready features such as lagged values, rolling statistics, and calendar signals. This is the first major boundary: raw synthetic data becomes structured training input.

3. The modeling layer is split by use case in `src/models/`. `lstm_model.py` defines and trains the demand forecaster using PyTorch LSTM logic, while `risk_model.py` trains the supplier risk classifier using XGBoost. These are separate model tracks, which is important architecturally because demand forecasting and supplier risk scoring have different inputs, outputs, and evaluation metrics.

4. Training artifacts appear to be persisted outside the source tree, with `models/` used for saved binaries and `mlruns/` for experiment tracking. The README indicates MLflow is used to track loss, MAE, and RMSE for both model families. So the training side is not just “fit a model,” but a reproducible experiment-and-artifact workflow.

5. Inference is handled in `src/forecasting/predictor.py` and `src/risk/scorer.py`. The predictor takes a trained demand model and generates the 28-day SKU forecast, including prediction intervals. The scorer combines the risk classifier output with SHAP explanations and produces risk labels and alert-style outputs. These modules are the bridge between trained models and API/dashboard consumers.

6. The LLM layer in `src/llm/insight_chain.py` adds a narrative-generation boundary on top of numeric outputs. It uses LangChain with a local Ollama model to synthesize forecast, risk, and reorder information into planner-readable text. This is a distinct subsystem from the predictive models: it does not forecast itself, but summarizes and contextualizes results.

7. `api/main.py` is the online service boundary. The FastAPI app exposes `/forecast`, `/risk`, `/insights`, and `/health`, which correspond directly to the three core capabilities plus liveness. The API is the integration layer that orchestrates the forecast engine, risk engine, and LLM chain into request/response workflows.

8. `dashboard/app.py` is the user-facing visualization boundary. The Streamlit app consumes API or local outputs to render the demand chart, supplier risk states, reorder alerts, and generated insights. This means the dashboard is not the analytical engine; it is a presentation layer on top of the backend services.

9. The repository also includes an M5 benchmark notebook in `notebooks/02_m5_forecasting.ipynb`. That notebook is a sidecar evaluation path for the same LSTM architecture on real Walmart-style retail data, separate from the synthetic industrial dataset used by the main system. Architecturally, it serves as validation and experimentation rather than part of the production request path.

10. Deployment and packaging are containerized with `Dockerfile.api`, `Dockerfile.dashboard`, and `docker-compose.yml`, which indicate the API and dashboard can run as separate services together. The requirements files split dependencies by runtime, and `.env.example` suggests configurable runtime settings. This is a clean multi-service layout rather than a single monolith.

11. Quality and governance are lightweight but explicit: `tests/test_generator.py` validates synthetic data generation and `tests/test_imports.py` keeps CI-safe import checks stable. `.github/workflows/ci.yml` automates these tests, and `AI_ACT_COMPLIANCE.md` indicates the repo includes documented compliance considerations. So the architecture includes both technical and process boundaries.

12. In diagram terms, the main flow is: synthetic data generation and preprocessing feed model training; trained models and MLflow artifacts feed inference modules; inference outputs feed the LLM narrative layer; and both API and dashboard sit on top as consumers. The most important separations are training vs serving, forecasting vs risk scoring, and numeric analytics vs natural-language explanation.

Main entry points: [`api/main.py`](https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/api/main.py) (FastAPI), [`src/forecasting/predictor.py`](https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/src/forecasting/predictor.py) (Forecasting), [`src/risk/scorer.py`](https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/src/risk/scorer.py) (Risk scoring), [`src/data/generator.py`](https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/src/data/generator.py) (Data gen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_data_ml["Data & ML"]
  node_node_data_gen["Data gen<br/>synthetic data<br/>[generator.py]"]
  node_node_data_prep["Prep features<br/>feature engineering<br/>[preprocess.py]"]
  node_node_lstm_train["Demand model<br/>PyTorch LSTM<br/>[lstm_model.py]"]
  node_node_risk_train["Risk model<br/>XGBoost classifier<br/>[risk_model.py]"]
  node_node_artifacts[("Artifacts<br/>model binaries")]
end

subgraph group_group_serving["Serving Layer"]
  node_node_predictor["Forecasting<br/>inference engine<br/>[predictor.py]"]
  node_node_scorer["Risk scoring<br/>inference engine<br/>[scorer.py]"]
  node_node_insights["Insights<br/>LLM chain<br/>[insight_chain.py]"]
end

subgraph group_group_apps["Applications"]
  node_node_api["FastAPI<br/>service API<br/>[main.py]"]
  node_node_dashboard["Streamlit<br/>presentation app<br/>[app.py]"]
  node_node_docker_api["API image<br/>container build<br/>[Dockerfile.api]"]
  node_node_docker_dash["Dash image<br/>container build"]
  node_node_compose["Compose<br/>service orchestration<br/>[docker-compose.yml]"]
end

subgraph group_group_quality["Quality & Validation"]
  node_node_notebook["M5 notebook<br/>benchmark notebook"]
  node_node_tests["Tests<br/>pytest suite<br/>[test_generator.py]"]
  node_node_ci["CI<br/>workflow<br/>[ci.yml]"]
  node_node_compliance["Compliance<br/>governance note"]
end

node_node_data_gen -->|"raw data"| node_node_data_prep
node_node_data_prep -->|"train input"| node_node_lstm_train
node_node_data_gen -->|"risk records"| node_node_risk_train
node_node_lstm_train -->|"save model"| node_node_artifacts
node_node_risk_train -->|"save model"| node_node_artifacts
node_node_artifacts -->|"load forecast"| node_node_predictor
node_node_artifacts -->|"load risk"| node_node_scorer
node_node_predictor -->|"forecast"| node_node_api
node_node_scorer -->|"risk"| node_node_api
node_node_predictor -->|"signals"| node_node_insights
node_node_scorer -->|"signals"| node_node_insights
node_node_insights -->|"insights"| node_node_api
node_node_api -->|"serve data"| node_node_dashboard
node_node_api -->|"package"| node_node_docker_api
node_node_dashboard -->|"package"| node_node_docker_dash
node_node_docker_api -->|"orchestrate"| node_node_compose
node_node_docker_dash -->|"orchestrate"| node_node_compose
node_node_notebook -.->|"evaluate"| node_node_lstm_train
node_node_tests -.->|"verify"| node_node_data_gen
node_node_ci -->|"run"| node_node_tests
node_node_compliance -.->|"govern"| node_node_api

click node_node_data_gen "https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/src/data/generator.py"
click node_node_data_prep "https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/src/data/preprocess.py"
click node_node_lstm_train "https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/src/models/lstm_model.py"
click node_node_risk_train "https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/src/models/risk_model.py"
click node_node_predictor "https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/src/forecasting/predictor.py"
click node_node_scorer "https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/src/risk/scorer.py"
click node_node_insights "https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/src/llm/insight_chain.py"
click node_node_api "https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/api/main.py"
click node_node_dashboard "https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/dashboard/app.py"
click node_node_docker_api "https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/Dockerfile.api"
click node_node_docker_dash "https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/Dockerfile.dashboard"
click node_node_compose "https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/docker-compose.yml"
click node_node_notebook "https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/notebooks/02_m5_forecasting.ipynb"
click node_node_tests "https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/tests/test_generator.py"
click node_node_ci "https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/.github/workflows/ci.yml"
click node_node_compliance "https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/AI_ACT_COMPLIANCE.md"

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_node_data_gen,node_node_data_prep,node_node_lstm_train,node_node_risk_train,node_node_artifacts toneBlue
class node_node_predictor,node_node_scorer,node_node_insights toneAmber
class node_node_api,node_node_dashboard,node_node_docker_api,node_node_docker_dash,node_node_compose toneMint
class node_node_notebook,node_node_tests,node_node_ci,node_node_compliance toneRose
```

## Components

### Data & ML

Synthetic data generation, preprocessing, model training, and experiment artifacts.

- [Data gen](https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/src/data/generator.py): synthetic data · Creates daily demand series and supplier risk records. · `src/data/generator.py`
- [Prep features](https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/src/data/preprocess.py): feature engineering · Builds model-ready lag, rolling, and calendar features from raw demand. · `src/data/preprocess.py`
- [Demand model](https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/src/models/lstm_model.py): PyTorch LSTM · Trains the demand forecaster for SKU-level time series prediction. · `src/models/lstm_model.py`
- [Risk model](https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/src/models/risk_model.py): XGBoost classifier · Trains the supplier risk classifier used for risk scoring. · `src/models/risk_model.py`
- **Artifacts**: model binaries · Saved model files and experiment tracking used by training and serving.

### Serving Layer

Forecasting, risk scoring, and narrative generation used at runtime.

- [Forecasting](https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/src/forecasting/predictor.py): inference engine · Generates 28-day demand forecasts and prediction intervals. · `src/forecasting/predictor.py`
- [Risk scoring](https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/src/risk/scorer.py): inference engine · Produces risk labels, alerts, and SHAP-based explanations. · `src/risk/scorer.py`
- [Insights](https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/src/llm/insight_chain.py): LLM chain · Synthesizes forecast, risk, and reorder context into narrative text. · `src/llm/insight_chain.py`

### Applications

API, dashboard, and deployment packaging around the shared core.

- [FastAPI](https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/api/main.py): service API · Exposes forecast, risk, insights, and health endpoints. · `api/main.py`
- [Streamlit](https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/dashboard/app.py): presentation app · Displays demand, supplier risk, alerts, and generated insights. · `dashboard/app.py`
- [API image](https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/Dockerfile.api): container build · Container definition for the backend service. · `Dockerfile.api`
- [Dash image](https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/Dockerfile.dashboard): container build · Container definition for the dashboard service. · `Dockerfile.dashboard`
- [Compose](https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/docker-compose.yml): service orchestration · Runs API and dashboard together as a multi-service stack. · `docker-compose.yml`

### Quality & Validation

Tests, benchmark notebook, and compliance/governance artifacts.

- [M5 notebook](https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/notebooks/02_m5_forecasting.ipynb): benchmark notebook · Sidecar evaluation of the LSTM architecture on benchmark retail data. · `notebooks/02_m5_forecasting.ipynb`
- [Tests](https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/tests/test_generator.py): pytest suite · Validates synthetic generation and import stability. · `tests/test_generator.py`
- [CI](https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/.github/workflows/ci.yml): workflow · Automated test execution in GitHub Actions. · `.github/workflows/ci.yml`
- [Compliance](https://github.com/kbajish/ai-supply-chain-forecasting/blob/main/AI_ACT_COMPLIANCE.md): governance note · Documents AI Act-related compliance considerations. · `AI_ACT_COMPLIANCE.md`

## Connections

- Data gen → Prep features: raw data · Synthetic demand data is transformed into training features.
- Prep features → Demand model: train input · Engineered demand features feed the forecaster.
- Data gen → Risk model: risk records · Synthetic supplier risk data feeds classifier training.
- Demand model → Artifacts: save model · Trained demand model is persisted as an artifact.
- Risk model → Artifacts: save model · Trained risk model is persisted as an artifact.
- Artifacts → Forecasting: load forecast · Inference reads trained demand artifacts.
- Artifacts → Risk scoring: load risk · Inference reads trained risk artifacts.
- Forecasting → FastAPI: forecast · API requests are served from the forecasting engine.
- Risk scoring → FastAPI: risk · API requests are served from the risk engine.
- Forecasting → Insights: signals · Forecast outputs contribute to narrative generation.
- Risk scoring → Insights: signals · Risk outputs contribute to narrative generation.
- Insights → FastAPI: insights · LLM-generated summaries are exposed through the API.
- FastAPI → Streamlit: serve data · Dashboard consumes backend endpoints or local outputs.
- FastAPI → API image: package · Backend service is containerized for deployment.
- Streamlit → Dash image: package · Dashboard service is containerized for deployment.
- API image → Compose: orchestrate · API container is part of the multi-service stack.
- Dash image → Compose: orchestrate · Dashboard container is part of the multi-service stack.
- M5 notebook → Demand model: evaluate · Benchmark notebook exercises the same forecasting architecture.
- Tests → Data gen: verify · Tests validate synthetic data generation behavior.
- CI → Tests: run · CI automates the test suite.
- Compliance → FastAPI: govern · Compliance guidance applies to the service boundary.
