# jdr-codes/ai-demand-forecasting architecture

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

- Interactive diagram: https://gitdiagram.com/jdr-codes/ai-demand-forecasting
- Repository: https://github.com/jdr-codes/ai-demand-forecasting

## Overview

This is a demand-forecasting and inventory-optimization application: users configure data sources, synchronize and process data, train or run forecasts, then use recommendations, scenarios, inventory views, alerts, and reports. The FastAPI application is the runtime entry point; the sampled admin frontend exposes authentication screens, while the tree indicates the broader product surface is primarily in backend routes and services. Edges reflect explicit imports, calls, or route registration in the excerpts and SOURCE INDEX; unsampled route implementations are represented by their directories, with uncertain links omitted.

Main entry points: [`Backend/fastapi_app/services/data_integration/data_source_service.py`](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/data_integration/data_source_service.py) (Data-source integration), [`Backend/fastapi_app/db/session.py`](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/db/session.py) (Application database), [`Backend/fastapi_app/services/data_processing/processing_job_service.py`](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/data_processing/processing_job_service.py) (Data processing), [`Backend/fastapi_app/services/scenario/simulation_engine.py`](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/scenario/simulation_engine.py) (Scenario simulation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_adminui["Admin interface<br/>[App.jsx]"]
  node_api["FastAPI application<br/>[main.py]"]
end

subgraph group_access["Access and identity"]
  node_authui["Login and OTP<br/>[Login.jsx]"]
  node_authroutes["Authentication routes<br/>[auth_router.py]"]
  node_authservice["Authentication service<br/>[auth_service.py]"]
  node_database[("Application database<br/>[session.py]")]
end

subgraph group_data["Data operations"]
  node_datasources["Data-source integration"]
  node_connectors["Source connectors"]
  node_scheduler["Scheduler"]
  node_processing["Data processing"]
  node_validation["Data validation"]
  node_background["Background task dispatch<br/>[task_manager.py]"]
end

subgraph group_planning["Forecast and planning"]
  node_forecast["Forecast execution"]
  node_forecastapi["Forecast routes<br/>[forecast_engine.py]"]
  node_training["Model training"]
  node_recommend["Recommendations"]
  node_scenario["Scenario simulation"]
end

subgraph group_insight["Operations and insight"]
  node_inventory["Inventory optimization"]
  node_dashboard["Dashboard services"]
  node_alerts["Alerts and notifications"]
  node_reports["Reports<br/>[report_service.py]"]
  node_websocket["Live updates"]
end

node_operator(("User or operator"))

node_operator -->|"uses"| node_adminui
node_adminui -->|"routes to"| node_authui
node_operator -.->|"requests"| node_api
node_api -->|"registers"| node_authroutes
node_api -->|"registers"| node_forecastapi
node_authui -.->|"authenticates"| node_authroutes
node_authroutes -->|"calls"| node_authservice
node_authservice -->|"reads and writes"| node_database
node_datasources -->|"uses"| node_connectors
node_datasources -->|"validates through"| node_validation
node_datasources -->|"configures"| node_scheduler
node_scheduler -->|"starts sync"| node_datasources
node_scheduler -->|"dispatches jobs"| node_background
node_processing -->|"validates data"| node_validation
node_processing -->|"sends progress"| node_websocket
node_forecastapi -->|"dispatches forecast"| node_background
node_forecastapi -->|"queries model"| node_database
node_background -.->|"runs job"| node_forecast
node_training -.->|"persists training"| node_database
node_scenario -->|"runs forecast"| node_forecast
node_scenario -->|"generates recommendations"| node_recommend
node_scenario -->|"broadcasts progress"| node_websocket
node_recommend -.->|"stores results"| node_database
node_dashboard -.->|"publishes updates"| node_websocket
node_processing -->|"notifies"| node_alerts
node_operator -.->|"reviews"| node_inventory
node_operator -.->|"requests reports"| node_reports
node_operator -.->|"views metrics"| node_dashboard

click node_adminui "https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Frontend/admin/src/App.jsx"
click node_api "https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/main.py"
click node_authui "https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Frontend/admin/src/pages/Authentication/Login.jsx"
click node_authroutes "https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/routes/auth_router.py"
click node_authservice "https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/auth/auth_service.py"
click node_database "https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/db/session.py"
click node_datasources "https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/data_integration/data_source_service.py"
click node_connectors "https://github.com/jdr-codes/ai-demand-forecasting/tree/main/Backend/fastapi_app/services/connectors"
click node_scheduler "https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/scheduler/scheduler_service.py"
click node_processing "https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/data_processing/processing_job_service.py"
click node_validation "https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/validation/validation_service.py"
click node_background "https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/background/task_manager.py"
click node_forecast "https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/forecast/forecast_execution_service.py"
click node_forecastapi "https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/routes/forecast_engine.py"
click node_training "https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/forecast/training_service.py"
click node_recommend "https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/recommendation/recommendation_generator_service.py"
click node_scenario "https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/scenario/simulation_engine.py"
click node_inventory "https://github.com/jdr-codes/ai-demand-forecasting/tree/main/Backend/fastapi_app/services/inventory"
click node_dashboard "https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/dashboard/dashboard_service.py"
click node_alerts "https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/notifications/notification_service.py"
click node_reports "https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/report/report_service.py"
click node_websocket "https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/websocket/websocket_manager.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_adminui,node_api,node_operator toneBlue
class node_authui,node_authroutes,node_authservice,node_database toneAmber
class node_datasources,node_connectors,node_scheduler,node_processing,node_validation,node_background toneMint
class node_forecast,node_forecastapi,node_training,node_recommend,node_scenario toneRose
class node_inventory,node_dashboard,node_alerts,node_reports,node_websocket toneIndigo
```

## Components

### Application entry

- [Admin interface](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Frontend/admin/src/App.jsx): `Frontend/admin/src/App.jsx`
- [FastAPI application](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/main.py): `Backend/fastapi_app/main.py`

### Access and identity

- [Login and OTP](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Frontend/admin/src/pages/Authentication/Login.jsx): `Frontend/admin/src/pages/Authentication/Login.jsx`
- [Authentication routes](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/routes/auth_router.py): `Backend/fastapi_app/routes/auth_router.py`
- [Authentication service](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/auth/auth_service.py): `Backend/fastapi_app/services/auth/auth_service.py`
- [Application database](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/db/session.py): `Backend/fastapi_app/db/session.py`

### Data operations

- [Data-source integration](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/data_integration/data_source_service.py): `Backend/fastapi_app/services/data_integration/data_source_service.py`
- [Source connectors](https://github.com/jdr-codes/ai-demand-forecasting/tree/main/Backend/fastapi_app/services/connectors): `Backend/fastapi_app/services/connectors`
- [Scheduler](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/scheduler/scheduler_service.py): `Backend/fastapi_app/services/scheduler/scheduler_service.py`
- [Data processing](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/data_processing/processing_job_service.py): `Backend/fastapi_app/services/data_processing/processing_job_service.py`
- [Data validation](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/validation/validation_service.py): `Backend/fastapi_app/services/validation/validation_service.py`
- [Background task dispatch](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/background/task_manager.py): `Backend/fastapi_app/services/background/task_manager.py`

### Forecast and planning

- [Forecast execution](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/forecast/forecast_execution_service.py): `Backend/fastapi_app/services/forecast/forecast_execution_service.py`
- [Forecast routes](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/routes/forecast_engine.py): `Backend/fastapi_app/routes/forecast_engine.py`
- [Model training](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/forecast/training_service.py): `Backend/fastapi_app/services/forecast/training_service.py`
- [Recommendations](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/recommendation/recommendation_generator_service.py): `Backend/fastapi_app/services/recommendation/recommendation_generator_service.py`
- [Scenario simulation](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/scenario/simulation_engine.py): `Backend/fastapi_app/services/scenario/simulation_engine.py`

### Operations and insight

- [Inventory optimization](https://github.com/jdr-codes/ai-demand-forecasting/tree/main/Backend/fastapi_app/services/inventory): `Backend/fastapi_app/services/inventory`
- [Dashboard services](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/dashboard/dashboard_service.py): `Backend/fastapi_app/services/dashboard/dashboard_service.py`
- [Alerts and notifications](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/notifications/notification_service.py): `Backend/fastapi_app/services/notifications/notification_service.py`
- [Reports](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/report/report_service.py): `Backend/fastapi_app/services/report/report_service.py`
- [Live updates](https://github.com/jdr-codes/ai-demand-forecasting/blob/main/Backend/fastapi_app/services/websocket/websocket_manager.py): `Backend/fastapi_app/services/websocket/websocket_manager.py`

### Other components

- **User or operator**

## Connections

- User or operator → Admin interface: uses (evidence: `Frontend/admin/src/App.jsx`)
- Admin interface → Login and OTP: routes to (evidence: `Frontend/admin/src/App.jsx`)
- User or operator → FastAPI application: requests
- FastAPI application → Authentication routes: registers (evidence: `Backend/fastapi_app/main.py`)
- FastAPI application → Forecast routes: registers (evidence: `Backend/fastapi_app/main.py`)
- Login and OTP → Authentication routes: authenticates
- Authentication routes → Authentication service: calls (evidence: `Backend/fastapi_app/routes/auth_router.py`)
- Authentication service → Application database: reads and writes (evidence: `Backend/fastapi_app/services/auth/auth_service.py`)
- Data-source integration → Source connectors: uses (evidence: `Backend/fastapi_app/services/data_integration/data_source_service.py`)
- Data-source integration → Data validation: validates through (evidence: `Backend/fastapi_app/services/data_integration/data_source_service.py`)
- Data-source integration → Scheduler: configures (evidence: `Backend/fastapi_app/services/data_integration/data_source_service.py`)
- Scheduler → Data-source integration: starts sync (evidence: `Backend/fastapi_app/services/scheduler/scheduler_service.py`)
- Scheduler → Background task dispatch: dispatches jobs (evidence: `Backend/fastapi_app/services/scheduler/scheduler_service.py`)
- Data processing → Data validation: validates data (evidence: `Backend/fastapi_app/services/data_processing/processing_job_service.py`)
- Data processing → Live updates: sends progress (evidence: `Backend/fastapi_app/services/data_processing/processing_job_service.py`)
- Forecast routes → Background task dispatch: dispatches forecast (evidence: `Backend/fastapi_app/routes/forecast_engine.py`)
- Forecast routes → Application database: queries model (evidence: `Backend/fastapi_app/routes/forecast_engine.py`)
- Background task dispatch → Forecast execution: runs job
- Model training → Application database: persists training
- Scenario simulation → Forecast execution: runs forecast (evidence: `Backend/fastapi_app/services/scenario/simulation_engine.py`)
- Scenario simulation → Recommendations: generates recommendations (evidence: `Backend/fastapi_app/services/scenario/simulation_engine.py`)
- Scenario simulation → Live updates: broadcasts progress (evidence: `Backend/fastapi_app/services/scenario/simulation_engine.py`)
- Recommendations → Application database: stores results
- Dashboard services → Live updates: publishes updates
- Data processing → Alerts and notifications: notifies (evidence: `Backend/fastapi_app/services/data_processing/processing_job_service.py`)
- User or operator → Inventory optimization: reviews
- User or operator → Reports: requests reports
- User or operator → Dashboard services: views metrics
