# aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws architecture

> Architecture diagram of the GitHub repository aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws
- Repository: https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws

## Overview

This is an AWS retail demand-forecasting product: merchandisers browse products and forecasts, project stock coverage, and explore price or purchase what-if scenarios; administrators upload sales data and monitor retraining. The documented backend catalogs and queries sales data, trains models, runs batch inference, and publishes forecasts, with optional real-time inference. The graph combines README-described service flow with sampled CDK and handler evidence; several frontend and Lambda subsystem internals were not sampled, so their links reflect documented architecture rather than inspected calls.

Main entry points: [`deployment/cdk/lib/stacks/backend-stack.ts`](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/deployment/cdk/lib/stacks/backend-stack.ts) (REST API), [`deployment/cdk/bin/app.ts`](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/deployment/cdk/bin/app.ts) (Infrastructure composition), [`source/frontend/app`](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/tree/main/source/frontend/app) (Forecasting web app), [`deployment/cdk/lib/stacks/pipeline-stack.ts`](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/deployment/cdk/lib/stacks/pipeline-stack.ts) (Step Functions workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_web["Forecasting web app"]
  node_authui["Authentication UI"]
  node_forecastui["Forecast exploration<br/>[page.tsx]"]
  node_adminui["Dataset and jobs UI"]
  node_client["API client<br/>[api-client.ts]"]
end

subgraph group_api["Application API"]
  node_gateway["REST API<br/>[backend-stack.ts]"]
  node_productapi["Product handlers"]
  node_forecastapi["Forecast handlers"]
  node_uploadapi["Dataset upload"]
  node_trainingapi["Training management"]
  node_inferenceapi["Inference operations"]
  node_shared["Forecast data helpers<br/>[forecast-data.ts]"]
end

subgraph group_data["Sales data"]
  node_rawdata[("Sales data store<br/>[data-stack.ts]")]
  node_catalog["Glue and Athena<br/>[athena-client.ts]"]
  node_outputs[("Forecast output store<br/>[data-stack.ts]")]
  node_uploadstatus[("Upload status store<br/>[backend-stack.ts]")]
end

subgraph group_ml["Forecast ML"]
  node_pipeline["Step Functions workflow<br/>[pipeline-stack.ts]"]
  node_training["SageMaker training<br/>[index.ts]"]
  node_batch["Batch inference<br/>[index.ts]"]
  node_endpoint["Real-time endpoint<br/>[index.ts]"]
end

subgraph group_platform["AWS platform"]
  node_cognito["Cognito identity<br/>[auth-stack.ts]"]
  node_hosting["Web hosting<br/>[frontend-stack.ts]"]
  node_stackapp["Infrastructure composition<br/>[app.ts]"]
end

node_merchandiser(("Merchandiser"))
node_admin(("Administrator"))

node_merchandiser -->|"explores"| node_web
node_admin -->|"administers"| node_web
node_web -->|"served by"| node_hosting
node_web -.->|"authenticates through"| node_authui
node_authui -->|"authenticates with"| node_cognito
node_forecastui -.->|"requests data"| node_client
node_adminui -.->|"requests operations"| node_client
node_client -->|"calls"| node_gateway
node_gateway -->|"routes"| node_productapi
node_gateway -->|"routes"| node_forecastapi
node_gateway -->|"routes"| node_uploadapi
node_gateway -->|"routes"| node_trainingapi
node_gateway -->|"routes"| node_inferenceapi
node_productapi -->|"reads metadata"| node_rawdata
node_forecastapi -->|"reads forecasts"| node_outputs
node_forecastapi -->|"loads forecast data"| node_shared
node_uploadapi -->|"writes uploads"| node_rawdata
node_uploadapi -->|"tracks status"| node_uploadstatus
node_rawdata -->|"upload triggers"| node_pipeline
node_pipeline -->|"orchestrates"| node_training
node_pipeline -->|"orchestrates"| node_batch
node_batch -->|"writes forecasts"| node_outputs
node_trainingapi -->|"manages jobs"| node_training
node_inferenceapi -.->|"invokes"| node_endpoint
node_endpoint -->|"stores results"| node_outputs
node_catalog -->|"queries sales data"| node_rawdata
node_stackapp -->|"instantiates"| node_cognito
node_stackapp -->|"instantiates"| node_gateway
node_stackapp -->|"instantiates"| node_pipeline
node_stackapp -->|"configures data stack"| node_outputs

click node_web "https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/tree/main/source/frontend/app"
click node_authui "https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/tree/main/source/frontend/components/auth"
click node_forecastui "https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/source/frontend/app/forecast/page.tsx"
click node_adminui "https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/tree/main/source/frontend/components/admin"
click node_client "https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/source/frontend/lib/api-client.ts"
click node_gateway "https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/deployment/cdk/lib/stacks/backend-stack.ts"
click node_productapi "https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/tree/main/source/lambda/products"
click node_forecastapi "https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/tree/main/source/lambda/forecasts"
click node_uploadapi "https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/tree/main/source/lambda/dataset-upload"
click node_trainingapi "https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/tree/main/source/lambda/training"
click node_inferenceapi "https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/tree/main/source/lambda/inference"
click node_shared "https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/source/lambda/shared/forecast-data.ts"
click node_rawdata "https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/deployment/cdk/lib/stacks/data-stack.ts"
click node_catalog "https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/source/lambda/shared/athena-client.ts"
click node_outputs "https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/deployment/cdk/lib/stacks/data-stack.ts"
click node_uploadstatus "https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/deployment/cdk/lib/stacks/backend-stack.ts"
click node_pipeline "https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/deployment/cdk/lib/stacks/pipeline-stack.ts"
click node_training "https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/source/lambda/pipeline/start-training/index.ts"
click node_batch "https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/source/lambda/pipeline/start-batch-inference/index.ts"
click node_endpoint "https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/source/lambda/inference/invoke-endpoint-worker/index.ts"
click node_cognito "https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/deployment/cdk/lib/stacks/auth-stack.ts"
click node_hosting "https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/deployment/cdk/lib/stacks/frontend-stack.ts"
click node_stackapp "https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/deployment/cdk/bin/app.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_web,node_authui,node_forecastui,node_adminui,node_client toneBlue
class node_gateway,node_productapi,node_forecastapi,node_uploadapi,node_trainingapi,node_inferenceapi,node_shared toneAmber
class node_rawdata,node_catalog,node_outputs,node_uploadstatus toneMint
class node_pipeline,node_training,node_batch,node_endpoint toneRose
class node_cognito,node_hosting,node_stackapp,node_merchandiser,node_admin toneIndigo
```

## Components

### Web experience

- [Forecasting web app](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/tree/main/source/frontend/app): `source/frontend/app`
- [Authentication UI](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/tree/main/source/frontend/components/auth): `source/frontend/components/auth`
- [Forecast exploration](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/source/frontend/app/forecast/page.tsx): `source/frontend/app/forecast/page.tsx`
- [Dataset and jobs UI](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/tree/main/source/frontend/components/admin): `source/frontend/components/admin`
- [API client](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/source/frontend/lib/api-client.ts): `source/frontend/lib/api-client.ts`

### Application API

- [REST API](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/deployment/cdk/lib/stacks/backend-stack.ts): `deployment/cdk/lib/stacks/backend-stack.ts`
- [Product handlers](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/tree/main/source/lambda/products): `source/lambda/products`
- [Forecast handlers](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/tree/main/source/lambda/forecasts): `source/lambda/forecasts`
- [Dataset upload](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/tree/main/source/lambda/dataset-upload): `source/lambda/dataset-upload`
- [Training management](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/tree/main/source/lambda/training): `source/lambda/training`
- [Inference operations](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/tree/main/source/lambda/inference): `source/lambda/inference`
- [Forecast data helpers](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/source/lambda/shared/forecast-data.ts): `source/lambda/shared/forecast-data.ts`

### Sales data

- [Sales data store](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/deployment/cdk/lib/stacks/data-stack.ts): `deployment/cdk/lib/stacks/data-stack.ts`
- [Glue and Athena](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/source/lambda/shared/athena-client.ts): `source/lambda/shared/athena-client.ts`
- [Forecast output store](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/deployment/cdk/lib/stacks/data-stack.ts): `deployment/cdk/lib/stacks/data-stack.ts`
- [Upload status store](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/deployment/cdk/lib/stacks/backend-stack.ts): `deployment/cdk/lib/stacks/backend-stack.ts`

### Forecast ML

- [Step Functions workflow](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/deployment/cdk/lib/stacks/pipeline-stack.ts): `deployment/cdk/lib/stacks/pipeline-stack.ts`
- [SageMaker training](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/source/lambda/pipeline/start-training/index.ts): `source/lambda/pipeline/start-training/index.ts`
- [Batch inference](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/source/lambda/pipeline/start-batch-inference/index.ts): `source/lambda/pipeline/start-batch-inference/index.ts`
- [Real-time endpoint](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/source/lambda/inference/invoke-endpoint-worker/index.ts): `source/lambda/inference/invoke-endpoint-worker/index.ts`

### AWS platform

- [Cognito identity](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/deployment/cdk/lib/stacks/auth-stack.ts): `deployment/cdk/lib/stacks/auth-stack.ts`
- [Web hosting](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/deployment/cdk/lib/stacks/frontend-stack.ts): `deployment/cdk/lib/stacks/frontend-stack.ts`
- [Infrastructure composition](https://github.com/aws-solutions-library-samples/guidance-for-demand-forecast-for-retail-on-aws/blob/main/deployment/cdk/bin/app.ts): `deployment/cdk/bin/app.ts`

### Other components

- **Merchandiser**
- **Administrator**

## Connections

- Merchandiser → Forecasting web app: explores (evidence: `README.md`)
- Administrator → Forecasting web app: administers (evidence: `README.md`)
- Forecasting web app → Web hosting: served by (evidence: `README.md`)
- Forecasting web app → Authentication UI: authenticates through
- Authentication UI → Cognito identity: authenticates with (evidence: `README.md`)
- Forecast exploration → API client: requests data
- Dataset and jobs UI → API client: requests operations
- API client → REST API: calls (evidence: `README.md`)
- REST API → Product handlers: routes (evidence: `README.md`)
- REST API → Forecast handlers: routes (evidence: `README.md`)
- REST API → Dataset upload: routes (evidence: `README.md`)
- REST API → Training management: routes (evidence: `README.md`)
- REST API → Inference operations: routes (evidence: `README.md`)
- Product handlers → Sales data store: reads metadata (evidence: `README.md`)
- Forecast handlers → Forecast output store: reads forecasts (evidence: `README.md`)
- Forecast handlers → Forecast data helpers: loads forecast data (evidence: `source/lambda/forecasts/run-what-if/index.ts`)
- Dataset upload → Sales data store: writes uploads (evidence: `README.md`)
- Dataset upload → Upload status store: tracks status (evidence: `README.md`)
- Sales data store → Step Functions workflow: upload triggers (evidence: `README.md`)
- Step Functions workflow → SageMaker training: orchestrates (evidence: `README.md`)
- Step Functions workflow → Batch inference: orchestrates (evidence: `README.md`)
- Batch inference → Forecast output store: writes forecasts (evidence: `README.md`)
- Training management → SageMaker training: manages jobs (evidence: `README.md`)
- Inference operations → Real-time endpoint: invokes
- Real-time endpoint → Forecast output store: stores results (evidence: `source/lambda/inference/invoke-endpoint-worker/index.ts`)
- Glue and Athena → Sales data store: queries sales data (evidence: `README.md`)
- Infrastructure composition → Cognito identity: instantiates (evidence: `deployment/cdk/bin/app.ts`)
- Infrastructure composition → REST API: instantiates (evidence: `deployment/cdk/bin/app.ts`)
- Infrastructure composition → Step Functions workflow: instantiates (evidence: `deployment/cdk/bin/app.ts`)
- Infrastructure composition → Forecast output store: configures data stack (evidence: `deployment/cdk/bin/app.ts`)
