# jerimiahbitancor/demand-forecasting-system architecture

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

- Interactive diagram: https://gitdiagram.com/jerimiahbitancor/demand-forecasting-system
- Repository: https://github.com/jerimiahbitancor/demand-forecasting-system

## Overview

This is a sales-demand forecasting and supply-planning application for micro food-service businesses. Users upload historical sales and recipe mappings, then review forecasts, product performance, ingredient requirements, inventory information, and alerts in the React interface. The Express API handles uploads and business operations; it delegates machine-learning work to a Flask service whose training and forecasting use XGBoost and persist models in Supabase Storage. The README documents broader analytics, reporting, settings, and notification capabilities. Some backend routes and services are unsampled, so their unverified links are omitted.

Main entry points: [`backend/server.js`](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/server.js) (HTTP API), [`frontend/src/App.jsx`](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/frontend/src/App.jsx) (Application routes), [`ml-service/app.py`](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/ml-service/app.py) (ML HTTP entry), [`backend/services/uploadService.js`](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/services/uploadService.js) (Sales upload processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_app["Application routes<br/>[App.jsx]"]
  node_authui["Authentication screens<br/>[Login.jsx]"]
  node_dataui["Sales data management<br/>[DataManagement.jsx]"]
  node_analyticsui["Forecast analytics<br/>[Analytics.jsx]"]
  node_inventoryui["Inventory management"]
  node_settingsui["Business settings<br/>[Settings.jsx]"]
  node_notifyui["Notifications"]
end

subgraph group_api["Business API"]
  node_server["HTTP API<br/>[server.js]"]
  node_uploads["Sales upload processing<br/>[uploadService.js]"]
  node_mapping["Recipe mapping<br/>[mappingService.js]"]
  node_inventory["Inventory operations"]
  node_alerts["Alerts and reminders"]
  node_productstatus["Product lifecycle"]
end

subgraph group_ml["Forecast service"]
  node_mlentry["ML HTTP entry<br/>[app.py]"]
  node_loader["Sales data loading<br/>[data_loader.py]"]
  node_zero["Open-day zero fill<br/>[zero_fill.py]"]
  node_features["Feature engineering"]
  node_businesslogic["Forecast business logic<br/>[business_logic.py]"]
  node_model["XGBoost modeling<br/>[model_service.py]"]
  node_modelstore["Model persistence<br/>[model_storage.py]"]
  node_mlconfig["ML configuration<br/>[config.py]"]
end

subgraph group_state["Persistence and operations"]
  node_supabase[("Supabase data access<br/>[supabase.js]")]
  node_audit["Audit records<br/>[auditService.js]"]
  node_paging["Paged row reads<br/>[fetchAllRows.js]"]
  node_units["Recipe unit conversion<br/>[recipeUnits.js]"]
  node_salesmods["Sales adjustments<br/>[salesModifiers.js]"]
  node_logger["Structured logging<br/>[logger.js]"]
end

node_owner(("Business user"))

node_owner -->|"uses"| node_app
node_app -->|"routes to"| node_authui
node_app -->|"routes to"| node_dataui
node_app -->|"routes to"| node_analyticsui
node_app -->|"routes to"| node_inventoryui
node_app -->|"routes to"| node_settingsui
node_app -->|"routes to"| node_notifyui
node_dataui -.->|"uploads data"| node_server
node_analyticsui -.->|"requests analytics"| node_server
node_inventoryui -.->|"requests operations"| node_server
node_settingsui -.->|"updates settings"| node_server
node_notifyui -.->|"requests alerts"| node_server
node_server -->|"routes requests"| node_uploads
node_uploads -->|"uses mappings"| node_mapping
node_uploads -->|"requests ML"| node_mlentry
node_server -->|"routes requests"| node_inventory
node_server -->|"routes requests"| node_alerts
node_uploads -->|"updates lifecycle"| node_productstatus
node_mlentry -->|"loads sales"| node_loader
node_mlentry -->|"builds forecasts"| node_features
node_mlentry -->|"runs pipeline"| node_businesslogic
node_mlentry -->|"trains or predicts"| node_model
node_model -->|"engineers features"| node_features
node_model -->|"loads models"| node_modelstore
node_features -->|"builds open days"| node_zero
node_mlentry -->|"loads model"| node_modelstore
node_inventory -->|"reads and writes"| node_supabase
node_inventory -->|"records actions"| node_audit
node_inventory -->|"converts quantities"| node_units
node_mapping -->|"converts recipe units"| node_units
node_uploads -->|"adjusts sales"| node_salesmods
node_alerts -->|"reads and writes"| node_supabase
node_mlentry -->|"uses settings"| node_mlconfig

click node_app "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/frontend/src/App.jsx"
click node_authui "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/frontend/src/features/auth/pages/login/Login.jsx"
click node_dataui "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/frontend/src/features/datamanagement/pages/DataManagement.jsx"
click node_analyticsui "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/frontend/src/features/analytics/pages/Analytics.jsx"
click node_inventoryui "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/frontend/src/features/inventory/pages/InventoryManagement.jsx"
click node_settingsui "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/frontend/src/features/settings/pages/Settings.jsx"
click node_notifyui "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/frontend/src/features/components/Notification/NotificationsPage.jsx"
click node_server "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/server.js"
click node_uploads "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/services/uploadService.js"
click node_mapping "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/services/mappingService.js"
click node_inventory "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/controllers/inventoryController.js"
click node_alerts "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/services/notificationService.js"
click node_productstatus "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/services/productStatusConstants.js"
click node_mlentry "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/ml-service/app.py"
click node_loader "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/ml-service/services/data_loader.py"
click node_zero "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/ml-service/services/zero_fill.py"
click node_features "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/ml-service/services/feature_engineering.py"
click node_businesslogic "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/ml-service/services/business_logic.py"
click node_model "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/ml-service/services/model_service.py"
click node_modelstore "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/ml-service/services/model_storage.py"
click node_supabase "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/config/supabase.js"
click node_audit "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/services/auditService.js"
click node_paging "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/utils/fetchAllRows.js"
click node_units "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/utils/recipeUnits.js"
click node_salesmods "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/utils/salesModifiers.js"
click node_logger "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/utils/logger.js"
click node_mlconfig "https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/ml-service/config.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_app,node_authui,node_dataui,node_analyticsui,node_inventoryui,node_settingsui,node_notifyui,node_owner toneBlue
class node_server,node_uploads,node_mapping,node_inventory,node_alerts,node_productstatus toneAmber
class node_mlentry,node_loader,node_zero,node_features,node_businesslogic,node_model,node_modelstore,node_mlconfig toneMint
class node_supabase,node_audit,node_paging,node_units,node_salesmods,node_logger toneRose
```

## Components

### Web application

- [Application routes](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Authentication screens](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/frontend/src/features/auth/pages/login/Login.jsx): `frontend/src/features/auth/pages/login/Login.jsx`
- [Sales data management](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/frontend/src/features/datamanagement/pages/DataManagement.jsx): `frontend/src/features/datamanagement/pages/DataManagement.jsx`
- [Forecast analytics](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/frontend/src/features/analytics/pages/Analytics.jsx): `frontend/src/features/analytics/pages/Analytics.jsx`
- [Inventory management](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/frontend/src/features/inventory/pages/InventoryManagement.jsx): `frontend/src/features/inventory/pages/InventoryManagement.jsx`
- [Business settings](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/frontend/src/features/settings/pages/Settings.jsx): `frontend/src/features/settings/pages/Settings.jsx`
- [Notifications](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/frontend/src/features/components/Notification/NotificationsPage.jsx): `frontend/src/features/components/Notification/NotificationsPage.jsx`

### Business API

- [HTTP API](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/server.js): `backend/server.js`
- [Sales upload processing](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/services/uploadService.js): `backend/services/uploadService.js`
- [Recipe mapping](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/services/mappingService.js): `backend/services/mappingService.js`
- [Inventory operations](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/controllers/inventoryController.js): `backend/controllers/inventoryController.js`
- [Alerts and reminders](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/services/notificationService.js): `backend/services/notificationService.js`
- [Product lifecycle](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/services/productStatusConstants.js): `backend/services/productStatusConstants.js`

### Forecast service

- [ML HTTP entry](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/ml-service/app.py): `ml-service/app.py`
- [Sales data loading](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/ml-service/services/data_loader.py): `ml-service/services/data_loader.py`
- [Open-day zero fill](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/ml-service/services/zero_fill.py): `ml-service/services/zero_fill.py`
- [Feature engineering](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/ml-service/services/feature_engineering.py): `ml-service/services/feature_engineering.py`
- [Forecast business logic](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/ml-service/services/business_logic.py): `ml-service/services/business_logic.py`
- [XGBoost modeling](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/ml-service/services/model_service.py): `ml-service/services/model_service.py`
- [Model persistence](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/ml-service/services/model_storage.py): `ml-service/services/model_storage.py`
- [ML configuration](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/ml-service/config.py): `ml-service/config.py`

### Persistence and operations

- [Supabase data access](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/config/supabase.js): `backend/config/supabase.js`
- [Audit records](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/services/auditService.js): `backend/services/auditService.js`
- [Paged row reads](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/utils/fetchAllRows.js): `backend/utils/fetchAllRows.js`
- [Recipe unit conversion](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/utils/recipeUnits.js): `backend/utils/recipeUnits.js`
- [Sales adjustments](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/utils/salesModifiers.js): `backend/utils/salesModifiers.js`
- [Structured logging](https://github.com/jerimiahbitancor/demand-forecasting-system/blob/staging/backend/utils/logger.js): `backend/utils/logger.js`

### Other components

- **Business user**

## Connections

- Business user → Application routes: uses
- Application routes → Authentication screens: routes to (evidence: `frontend/src/App.jsx`)
- Application routes → Sales data management: routes to (evidence: `frontend/src/App.jsx`)
- Application routes → Forecast analytics: routes to (evidence: `frontend/src/App.jsx`)
- Application routes → Inventory management: routes to (evidence: `frontend/src/App.jsx`)
- Application routes → Business settings: routes to (evidence: `frontend/src/App.jsx`)
- Application routes → Notifications: routes to (evidence: `frontend/src/App.jsx`)
- Sales data management → HTTP API: uploads data
- Forecast analytics → HTTP API: requests analytics
- Inventory management → HTTP API: requests operations
- Business settings → HTTP API: updates settings
- Notifications → HTTP API: requests alerts
- HTTP API → Sales upload processing: routes requests (evidence: `backend/server.js`)
- Sales upload processing → Recipe mapping: uses mappings (evidence: `backend/services/uploadService.js`)
- Sales upload processing → ML HTTP entry: requests ML (evidence: `backend/services/uploadService.js`)
- HTTP API → Inventory operations: routes requests (evidence: `backend/server.js`)
- HTTP API → Alerts and reminders: routes requests (evidence: `backend/server.js`)
- Sales upload processing → Product lifecycle: updates lifecycle (evidence: `backend/services/uploadService.js`)
- ML HTTP entry → Sales data loading: loads sales (evidence: `ml-service/app.py`)
- ML HTTP entry → Feature engineering: builds forecasts (evidence: `ml-service/app.py`)
- ML HTTP entry → Forecast business logic: runs pipeline (evidence: `ml-service/app.py`)
- ML HTTP entry → XGBoost modeling: trains or predicts (evidence: `ml-service/app.py`)
- XGBoost modeling → Feature engineering: engineers features (evidence: `ml-service/services/model_service.py`)
- XGBoost modeling → Model persistence: loads models (evidence: `ml-service/services/model_service.py`)
- Feature engineering → Open-day zero fill: builds open days (evidence: `ml-service/services/feature_engineering.py`)
- ML HTTP entry → Model persistence: loads model (evidence: `ml-service/app.py`)
- Inventory operations → Supabase data access: reads and writes (evidence: `backend/controllers/inventoryController.js`)
- Inventory operations → Audit records: records actions (evidence: `backend/controllers/inventoryController.js`)
- Inventory operations → Recipe unit conversion: converts quantities (evidence: `backend/controllers/inventoryController.js`)
- Recipe mapping → Recipe unit conversion: converts recipe units (evidence: `backend/services/mappingService.js`)
- Sales upload processing → Sales adjustments: adjusts sales (evidence: `backend/services/uploadService.js`)
- Alerts and reminders → Supabase data access: reads and writes (evidence: `backend/services/notificationService.js`)
- ML HTTP entry → ML configuration: uses settings (evidence: `ml-service/app.py`)
