+When a user creates a new request via the frontend, it travels through SQS, a Step Functions state machine, and two Python Lambda functions before the result is written to S3. The frontend polls the API to display live status transitions (`QUEUED → PROCESSING → FINISHED`).
+
+## Architecture
+
+The following diagram shows the architecture that this sample application builds and deploys:
+
+
+
+- **API Gateway (REST)** — exposes `POST /requests` and `GET /requests` endpoints backed by a Node.js Lambda function.
+- **[SQS](https://docs.localstack.cloud/user-guide/aws/sqs/)** — decouples the HTTP handler from the processing pipeline; the Node.js Lambda enqueues each new request.
+- **[Lambda](https://docs.localstack.cloud/user-guide/aws/lambda/)** — three runtimes in play:
+ - **Node.js** (`httpHandleRequest`) — handles HTTP requests, writes initial status to DynamoDB, enqueues to SQS.
+ - **Ruby** (`sqsHandleItem`) — consumes SQS messages and triggers the Step Functions execution.
+ - **Python** (`backendProcessRequest`, `backendArchiveResult`) — processes and archives results.
+- **[Step Functions](https://docs.localstack.cloud/user-guide/aws/stepfunctions/)** — orchestrates the two-step processing pipeline.
+- **[DynamoDB](https://docs.localstack.cloud/user-guide/aws/dynamodb/)** — stores request status at every stage.
+- **[S3](https://docs.localstack.cloud/user-guide/aws/s3/)** — stores the final result file and serves the React frontend.
## Prerequisites
-* LocalStack
-* Docker
-* Node.js / `yarn`
-* `make`
-* (optional) jq
+- A valid [LocalStack for AWS license](https://localstack.cloud/pricing). Your license provides a [`LOCALSTACK_AUTH_TOKEN`](https://docs.localstack.cloud/getting-started/auth-token/) to activate LocalStack.
+- [`localstack` CLI](https://docs.localstack.cloud/getting-started/installation/#localstack-cli).
+- [AWS CLI](https://docs.localstack.cloud/user-guide/integrations/aws-cli/) with the [`awslocal` wrapper](https://docs.localstack.cloud/user-guide/integrations/aws-cli/#localstack-aws-cli-awslocal).
+- [CDK](https://docs.localstack.cloud/user-guide/integrations/aws-cdk/) with the [`cdklocal`](https://www.npmjs.com/package/aws-cdk-local) wrapper (installed automatically via `cdk/package.json`).
+- [Node.js 22+](https://nodejs.org/en/download/)
+- [Docker](https://docs.docker.com/get-docker/) — required to bundle Ruby Lambda gems.
+- [`jq`](https://jqlang.github.io/jq/download/)
+- [`make`](https://www.gnu.org/software/make/)
-Note: Please make sure to pull and start the `latest` LocalStack Docker image. At the time of writing (2023-02-01), the demo requires some features that were only recently added to LocalStack and are not part of a tagged release version yet.
+## Installation
-## Running LocalStack
+Clone the repository:
-Use the `localstack` CLI command to get started:
+```bash
+git clone https://github.com/localstack/localstack-demo.git
+cd localstack-demo
```
-localstack start
+
+Install the CDK project dependencies:
+
+```bash
+make install
```
-## Installing dependencies & running the application
+## Deployment
-To install the dependencies, deploy and start the application locally in LocalStack:
+Set your LocalStack auth token and start LocalStack:
+
+```bash
+export LOCALSTACK_AUTH_TOKEN=Discovering API endpoint…
} + {!discovering && !baseURL && ( ++ Could not discover API Gateway. Make sure LocalStack is running and the stack is deployed. +
+ )} +| Timestamp | Request ID | Status | Action |
|---|---|---|---|
| Timestamp | Request ID | Status | Action |
{req.requestID}- This sample app illustrates a typical Web application scenario with asynchronous request processing happening in the background, all running locally inside LocalStack. -
- The end-to-end process is illustrated in the figure on the right. -
- Here's how the app works: + This sample app illustrates a typical Web application scenario with asynchronous + request processing happening in the background, all running locally inside LocalStack.
+The end-to-end process is illustrated in the figure on the right.
+Here's how the app works:
(Note that all resources will be deployed to the local "us-east-1" region.)
- (Note that all resources will be deployed to the local "us-east-1" region.) -
- The full source code of this sample is available in this Github repo: https://github.com/localstack/localstack-demo + The full source code of this sample is available on GitHub: + + https://github.com/localstack/localstack-demo +