This sample demonstrates a typical web application scenario where requests are accepted by a REST API and processed asynchronously in the background — all running locally inside LocalStack. The infrastructure is defined with AWS CDK and uses three different Lambda runtimes (Node.js, Python, and Ruby) to showcase a polyglot serverless architecture.

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).

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 — decouples the HTTP handler from the processing pipeline; the Node.js Lambda enqueues each new request.
• 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 — orchestrates the two-step processing pipeline.
• DynamoDB — stores request status at every stage.
• S3 — stores the final result file and serves the React frontend.

• A valid LocalStack for AWS license. Your license provides a LOCALSTACK_AUTH_TOKEN to activate LocalStack.
• lstk CLI, installed via npm install -g @localstack/lstk or brew install localstack/tap/lstk.
• AWS CLI, required by lstk aws.
• CDK installed globally (npm install -g aws-cdk), used via the lstk cdk proxy.
• Node.js 22+
• Docker — required to bundle Ruby Lambda gems.
• jq
• make

Clone the repository:

git clone https://github.com/localstack/localstack-demo.git
cd localstack-demo

Install the CDK project dependencies:

make install

Set your LocalStack auth token and start LocalStack:

export LOCALSTACK_AUTH_TOKEN=<your-auth-token>
make start

Deploy the full stack (bundles Lambda dependencies, bootstraps CDK, deploys, uploads frontend):

make deploy

The output will be similar to the following:

LocalstackDemoStack: deploying... [1/1]
...
 ✅  LocalstackDemoStack

Outputs:
LocalstackDemoStack.ApiEndpoint = https://<api-id>.execute-api.localhost.localstack.cloud:4566/local/
LocalstackDemoStack.WebsiteUrl  = http://localhost:4566/archive-bucket/index.html

Done! Open http://localhost:4566/archive-bucket/index.html in your browser.

Open the frontend in your browser:

http://localhost:4566/archive-bucket/index.html

• Enable Auto-Refresh to continuously poll for new results.
• Click Create new request to send a new request to the backend API.
• Watch the request move through QUEUED → PROCESSING → FINISHED in the table.
• When the status is FINISHED, a Download result link appears pointing to the result file in S3.

To send a request from the terminal and poll S3 until the result appears:

make send-request

The output will be similar to the following:

Looking up REST API ID...
Sending request to API ID 'lgbmikdf4o' ...
Received request ID 'e5503b47'
Polling s3://archive-bucket/ for result ...
                           PRE e5503b47/

You can also browse the contents of the archive bucket directly:

lstk aws s3 ls s3://archive-bucket/

This sample application demonstrates how to build and test a polyglot serverless pipeline using AWS CDK and LocalStack:

• Defining AWS infrastructure (API Gateway, Lambda, SQS, Step Functions, DynamoDB, S3) entirely with AWS CDK in TypeScript.
• Running three Lambda runtimes (Node.js, Python, Ruby) side-by-side in the same CDK stack.
• Serving a React frontend from S3 that auto-discovers the API Gateway endpoint and polls for status updates.
• Using the lstk cdk and lstk aws proxies to streamline local deployment and testing without touching real AWS.
• Providing a GitHub Actions workflow that runs the full integration test suite on every push.

• LocalStack Lambda documentation
• LocalStack Step Functions documentation
• Deploying AWS CDK applications with LocalStack
• AWS CDK documentation