# piyush314159/demandcast-retail_demand_forcasting-inventory_optimization architecture

> Architecture diagram of the GitHub repository piyush314159/demandcast-retail_demand_forcasting-inventory_optimization, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization
- Repository: https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization

## Overview

DemandCast is a retail-sales forecasting system with a Python pipeline and a Next.js dashboard. Its main workflow loads sales into MySQL, builds calendar-aware features, trains and evaluates multiple forecasting approaches, and exports saved results for dashboard exploration. The README also documents reconciliation, data-quality checks, export formats, and an assumption-based inventory calculator. Some dashboard and model connections are based on README statements or source-index references; unsampled implementation details are not inferred.

Main entry points: [`run_pipeline.py`](https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/run_pipeline.py) (Stage runner), [`src/data/database.py`](https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/data/database.py) (MySQL sales and forecasts), [`src/models/train_lightgbm.py`](https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/models/train_lightgbm.py) (LightGBM), [`src/evaluation/export_dashboard.py`](https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/evaluation/export_dashboard.py) (Dashboard snapshot exporter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Pipeline orchestration"]
  node_runner["Stage runner<br/>[run_pipeline.py]"]
end

subgraph group_data["Sales data"]
  node_ingest["Sales ingestion<br/>[load_data.py]"]
  node_store[("MySQL sales and forecasts<br/>[database.py]")]
  node_features["Calendar and lag features<br/>[build_features.py]"]
end

subgraph group_forecasting["Forecasting"]
  node_naive["Seasonal naive<br/>[baseline_naive.py]"]
  node_sarima["SARIMA<br/>[baseline_sarima.py]"]
  node_prophet["Prophet"]
  node_lightgbm["LightGBM<br/>[train_lightgbm.py]"]
  node_gru["Attention GRU<br/>[train_gru.py]"]
  node_reconcile["Bottom-up reconciliation<br/>[reconcile.py]"]
end

subgraph group_evaluation["Evaluation and export"]
  node_metrics["Forecast metrics<br/>[metrics.py]"]
  node_exporter["Dashboard snapshot exporter"]
end

subgraph group_dashboard["Dashboard"]
  node_snapshot["Exported workspace snapshot"]
  node_workspace_api["Workspace API<br/>[route.ts]"]
  node_workspace_reader["Snapshot reader"]
  node_workspace_types["Workspace data types<br/>[workspace.ts]"]
  node_workspace_ui["Forecast workspace"]
  node_chat_api["Evidence guide API<br/>[route.ts]"]
end

node_operator(("Pipeline operator"))

node_operator -->|"runs stages"| node_runner
node_runner -->|"invokes"| node_ingest
node_runner -->|"invokes"| node_features
node_runner -->|"invokes"| node_naive
node_runner -->|"invokes"| node_sarima
node_runner -->|"invokes"| node_prophet
node_runner -->|"invokes"| node_lightgbm
node_runner -->|"invokes"| node_gru
node_runner -->|"invokes"| node_reconcile
node_runner -->|"invokes"| node_exporter
node_ingest -->|"writes sales"| node_store
node_features -->|"reads sales"| node_store
node_lightgbm -->|"evaluates with"| node_metrics
node_lightgbm -->|"writes forecasts"| node_store
node_exporter -->|"reads saved data"| node_store
node_exporter -->|"writes snapshot"| node_snapshot
node_workspace_api -.->|"serves snapshot"| node_workspace_reader
node_workspace_reader -->|"reads"| node_snapshot
node_workspace_reader -->|"validates as"| node_workspace_types
node_workspace_ui -.->|"loads workspace"| node_workspace_api
node_workspace_ui -.->|"requests guide"| node_chat_api

click node_runner "https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/run_pipeline.py"
click node_ingest "https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/data/load_data.py"
click node_store "https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/data/database.py"
click node_features "https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/features/build_features.py"
click node_naive "https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/models/baseline_naive.py"
click node_sarima "https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/models/baseline_sarima.py"
click node_prophet "https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/models/baseline_prophet.py"
click node_lightgbm "https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/models/train_lightgbm.py"
click node_gru "https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/models/train_gru.py"
click node_reconcile "https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/models/reconcile.py"
click node_metrics "https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/evaluation/metrics.py"
click node_exporter "https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/evaluation/export_dashboard.py"
click node_snapshot "https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/tree/main/dashboard/data"
click node_workspace_api "https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/dashboard/app/api/workspace/route.ts"
click node_workspace_reader "https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/dashboard/lib/server-workspace.ts"
click node_workspace_types "https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/dashboard/lib/workspace.ts"
click node_workspace_ui "https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/dashboard/components/ForecastWorkspace.tsx"
click node_chat_api "https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/dashboard/app/api/chat/route.ts"

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_runner toneBlue
class node_ingest,node_store,node_features toneAmber
class node_naive,node_sarima,node_prophet,node_lightgbm,node_gru,node_reconcile toneMint
class node_metrics,node_exporter toneRose
class node_snapshot,node_workspace_api,node_workspace_reader,node_workspace_types,node_workspace_ui,node_chat_api,node_operator toneIndigo
```

## Components

### Pipeline orchestration

- [Stage runner](https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/run_pipeline.py): `run_pipeline.py`

### Sales data

- [Sales ingestion](https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/data/load_data.py): `src/data/load_data.py`
- [MySQL sales and forecasts](https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/data/database.py): `src/data/database.py`
- [Calendar and lag features](https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/features/build_features.py): `src/features/build_features.py`

### Forecasting

- [Seasonal naive](https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/models/baseline_naive.py): `src/models/baseline_naive.py`
- [SARIMA](https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/models/baseline_sarima.py): `src/models/baseline_sarima.py`
- [Prophet](https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/models/baseline_prophet.py): `src/models/baseline_prophet.py`
- [LightGBM](https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/models/train_lightgbm.py): `src/models/train_lightgbm.py`
- [Attention GRU](https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/models/train_gru.py): `src/models/train_gru.py`
- [Bottom-up reconciliation](https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/models/reconcile.py): `src/models/reconcile.py`

### Evaluation and export

- [Forecast metrics](https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/evaluation/metrics.py): `src/evaluation/metrics.py`
- [Dashboard snapshot exporter](https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/src/evaluation/export_dashboard.py): `src/evaluation/export_dashboard.py`

### Dashboard

- [Exported workspace snapshot](https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/tree/main/dashboard/data): `dashboard/data`
- [Workspace API](https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/dashboard/app/api/workspace/route.ts): `dashboard/app/api/workspace/route.ts`
- [Snapshot reader](https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/dashboard/lib/server-workspace.ts): `dashboard/lib/server-workspace.ts`
- [Workspace data types](https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/dashboard/lib/workspace.ts): `dashboard/lib/workspace.ts`
- [Forecast workspace](https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/dashboard/components/ForecastWorkspace.tsx): `dashboard/components/ForecastWorkspace.tsx`
- [Evidence guide API](https://github.com/piyush314159/demandcast-retail_demand_forcasting-inventory_optimization/blob/main/dashboard/app/api/chat/route.ts): `dashboard/app/api/chat/route.ts`

### Other components

- **Pipeline operator**

## Connections

- Pipeline operator → Stage runner: runs stages (evidence: `README.md`)
- Stage runner → Sales ingestion: invokes (evidence: `run_pipeline.py`)
- Stage runner → Calendar and lag features: invokes (evidence: `run_pipeline.py`)
- Stage runner → Seasonal naive: invokes (evidence: `run_pipeline.py`)
- Stage runner → SARIMA: invokes (evidence: `run_pipeline.py`)
- Stage runner → Prophet: invokes (evidence: `run_pipeline.py`)
- Stage runner → LightGBM: invokes (evidence: `run_pipeline.py`)
- Stage runner → Attention GRU: invokes (evidence: `run_pipeline.py`)
- Stage runner → Bottom-up reconciliation: invokes (evidence: `run_pipeline.py`)
- Stage runner → Dashboard snapshot exporter: invokes (evidence: `run_pipeline.py`)
- Sales ingestion → MySQL sales and forecasts: writes sales (evidence: `src/data/load_data.py`)
- Calendar and lag features → MySQL sales and forecasts: reads sales (evidence: `src/features/build_features.py`)
- LightGBM → Forecast metrics: evaluates with (evidence: `src/models/train_lightgbm.py`)
- LightGBM → MySQL sales and forecasts: writes forecasts (evidence: `src/models/train_lightgbm.py`)
- Dashboard snapshot exporter → MySQL sales and forecasts: reads saved data (evidence: `src/evaluation/export_dashboard.py`)
- Dashboard snapshot exporter → Exported workspace snapshot: writes snapshot (evidence: `src/evaluation/export_dashboard.py`)
- Workspace API → Snapshot reader: serves snapshot
- Snapshot reader → Exported workspace snapshot: reads (evidence: `dashboard/lib/server-workspace.ts`)
- Snapshot reader → Workspace data types: validates as (evidence: `dashboard/lib/server-workspace.ts`)
- Forecast workspace → Workspace API: loads workspace
- Forecast workspace → Evidence guide API: requests guide