# bs-prime/retail-demand-forecasting-and-inventory-optimization-system architecture

> Architecture diagram of the GitHub repository bs-prime/retail-demand-forecasting-and-inventory-optimization-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system
- Repository: https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system

## Overview

This is a retail demand forecasting and inventory-planning application. Its principal workflow accepts product/store inputs, predicts demand, converts forecasts into replenishment metrics, and presents plans through a dashboard or API. A separate training workflow prepares historical data, fits and evaluates forecasting models, and saves model and preprocessing artifacts. The README documents time-aware validation, SHAP explainability, single and batch inference, and configurable inventory planning; the sampled source confirms the orchestration and serving paths, but not every training component’s internals.

Main entry points: [`src/pipeline/train_pipeline.py`](https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/pipeline/train_pipeline.py) (Training orchestrator), [`src/pipeline/predict_pipeline.py`](https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/pipeline/predict_pipeline.py) (Prediction pipeline), [`src/api/app.py`](https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/api/app.py) (FastAPI service), [`src/services/inventory_service.py`](https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/services/inventory_service.py) (Inventory service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_training["Model training"]
  node_train_pipeline["Training orchestrator<br/>[train_pipeline.py]"]
  node_ingestion["Data ingestion<br/>[data_ingestion.py]"]
  node_cleaning["Data cleaning<br/>[data_cleaning.py]"]
  node_feature_engineering["Feature engineering"]
  node_preprocessing["Preprocessing"]
  node_model_training["Model training<br/>[model_training.py]"]
  node_evaluation["Model evaluation"]
  node_explainability["SHAP explainability"]
end

subgraph group_inference["Forecast inference"]
  node_predict_pipeline["Prediction pipeline"]
end

subgraph group_planning["Inventory planning"]
  node_inventory_service["Inventory service"]
  node_optimizer["EOQ and reorder logic<br/>[optimization.py]"]
end

subgraph group_interfaces["User interfaces"]
  node_api["FastAPI service<br/>[app.py]"]
  node_api_schemas["Request schemas<br/>[schemas.py]"]
  node_dashboard["Streamlit dashboard<br/>[main.py]"]
end

subgraph group_artifacts["Data and artifacts"]
  node_retail_data["Retail history"]
  node_features_artifacts["Feature datasets<br/>[train.csv]"]
  node_preprocessor_artifact["Preprocessor artifact<br/>[preprocessor.pkl]"]
  node_model_artifact["Best model<br/>[best_model.pkl]"]
end

node_business_user(("Retail planner"))
node_api_client(("API client"))

node_train_pipeline -->|"calls"| node_ingestion
node_ingestion -->|"reads"| node_retail_data
node_train_pipeline -->|"calls"| node_cleaning
node_train_pipeline -->|"calls"| node_feature_engineering
node_train_pipeline -->|"calls"| node_preprocessing
node_preprocessing -->|"writes"| node_features_artifacts
node_train_pipeline -->|"calls"| node_model_training
node_train_pipeline -->|"calls"| node_evaluation
node_train_pipeline -->|"writes"| node_model_artifact
node_train_pipeline -->|"writes"| node_preprocessor_artifact
node_train_pipeline -->|"calls"| node_explainability
node_predict_pipeline -->|"calls"| node_cleaning
node_predict_pipeline -->|"calls"| node_feature_engineering
node_predict_pipeline -->|"loads"| node_model_artifact
node_predict_pipeline -->|"returns forecasts to caller"| node_inventory_service
node_inventory_service -->|"calls"| node_optimizer
node_api_client -->|"requests"| node_api
node_api -->|"validates with"| node_api_schemas
node_api -->|"calls"| node_predict_pipeline
node_api -->|"calls"| node_inventory_service
node_business_user -->|"uses"| node_dashboard
node_dashboard -->|"calls"| node_predict_pipeline
node_dashboard -->|"calls"| node_inventory_service

click node_retail_data "https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/data/demand_forecasting.csv"
click node_train_pipeline "https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/pipeline/train_pipeline.py"
click node_ingestion "https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/components/data_ingestion.py"
click node_cleaning "https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/components/data_cleaning.py"
click node_feature_engineering "https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/components/feature_engineering.py"
click node_preprocessing "https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/components/data_preprocessing.py"
click node_model_training "https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/components/model_training.py"
click node_evaluation "https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/components/model_evaluation.py"
click node_explainability "https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/components/model_explainability.py"
click node_features_artifacts "https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/artifacts/features/train.csv"
click node_preprocessor_artifact "https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/artifacts/preprocessor/preprocessor.pkl"
click node_model_artifact "https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/models/best_model.pkl"
click node_predict_pipeline "https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/pipeline/predict_pipeline.py"
click node_inventory_service "https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/services/inventory_service.py"
click node_optimizer "https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/optimization_strategy/optimization.py"
click node_api "https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/api/app.py"
click node_api_schemas "https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/api/schemas.py"
click node_dashboard "https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/ui/main.py"

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_train_pipeline,node_ingestion,node_cleaning,node_feature_engineering,node_preprocessing,node_model_training,node_evaluation,node_explainability,node_api_client toneBlue
class node_predict_pipeline toneAmber
class node_inventory_service,node_optimizer toneMint
class node_api,node_api_schemas,node_dashboard toneRose
class node_retail_data,node_features_artifacts,node_preprocessor_artifact,node_model_artifact,node_business_user toneIndigo
```

## Components

### Model training

- [Training orchestrator](https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/pipeline/train_pipeline.py): `src/pipeline/train_pipeline.py`
- [Data ingestion](https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/components/data_ingestion.py): `src/components/data_ingestion.py`
- [Data cleaning](https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/components/data_cleaning.py): `src/components/data_cleaning.py`
- [Feature engineering](https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/components/feature_engineering.py): `src/components/feature_engineering.py`
- [Preprocessing](https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/components/data_preprocessing.py): `src/components/data_preprocessing.py`
- [Model training](https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/components/model_training.py): `src/components/model_training.py`
- [Model evaluation](https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/components/model_evaluation.py): `src/components/model_evaluation.py`
- [SHAP explainability](https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/components/model_explainability.py): `src/components/model_explainability.py`

### Forecast inference

- [Prediction pipeline](https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/pipeline/predict_pipeline.py): `src/pipeline/predict_pipeline.py`

### Inventory planning

- [Inventory service](https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/services/inventory_service.py): `src/services/inventory_service.py`
- [EOQ and reorder logic](https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/optimization_strategy/optimization.py): `src/optimization_strategy/optimization.py`

### User interfaces

- [FastAPI service](https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/api/app.py): `src/api/app.py`
- [Request schemas](https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/api/schemas.py): `src/api/schemas.py`
- [Streamlit dashboard](https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/src/ui/main.py): `src/ui/main.py`

### Data and artifacts

- [Retail history](https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/data/demand_forecasting.csv): `data/demand_forecasting.csv`
- [Feature datasets](https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/artifacts/features/train.csv): `artifacts/features/train.csv`
- [Preprocessor artifact](https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/artifacts/preprocessor/preprocessor.pkl): `artifacts/preprocessor/preprocessor.pkl`
- [Best model](https://github.com/bs-prime/retail-demand-forecasting-and-inventory-optimization-system/blob/main/models/best_model.pkl): `models/best_model.pkl`

### Other components

- **Retail planner**
- **API client**

## Connections

- Training orchestrator → Data ingestion: calls
- Data ingestion → Retail history: reads
- Training orchestrator → Data cleaning: calls
- Training orchestrator → Feature engineering: calls
- Training orchestrator → Preprocessing: calls
- Preprocessing → Feature datasets: writes
- Training orchestrator → Model training: calls
- Training orchestrator → Model evaluation: calls
- Training orchestrator → Best model: writes
- Training orchestrator → Preprocessor artifact: writes
- Training orchestrator → SHAP explainability: calls
- Prediction pipeline → Data cleaning: calls
- Prediction pipeline → Feature engineering: calls
- Prediction pipeline → Best model: loads
- Prediction pipeline → Inventory service: returns forecasts to caller
- Inventory service → EOQ and reorder logic: calls
- API client → FastAPI service: requests
- FastAPI service → Request schemas: validates with
- FastAPI service → Prediction pipeline: calls
- FastAPI service → Inventory service: calls
- Retail planner → Streamlit dashboard: uses
- Streamlit dashboard → Prediction pipeline: calls
- Streamlit dashboard → Inventory service: calls