| Key | Value |
|---|---|
| Environment | LocalStack, AWS |
| Services | Lambda, DynamoDB, SQS, Step Functions, API Gateway, S3 |
| Integrations | AWS CDK, AWS CLI, Docker, LocalStack |
| Categories | Serverless, Compute |
| Level | Intermediate |
| Use Case | Asynchronous Request Processing |
| GitHub | Repository link |
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 /requestsandGET /requestsendpoints 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.
- Node.js (
- 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_TOKENto activate LocalStack. localstackCLI.- AWS CLI with the
awslocalwrapper. - CDK with the
cdklocalwrapper (installed automatically viacdk/package.json). - Node.js 22+
- Docker — required to bundle Ruby Lambda gems.
jqmake
Clone the repository:
git clone https://github.com/localstack/localstack-demo.git
cd localstack-demoInstall the CDK project dependencies:
make installSet your LocalStack auth token and start LocalStack:
export LOCALSTACK_AUTH_TOKEN=<your-auth-token>
make start
make readyDeploy the full stack (bundles Lambda dependencies, bootstraps CDK, deploys, uploads frontend):
make deployThe 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 → FINISHEDin 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-requestThe 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:
awslocal 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
cdklocalandawslocalto streamline local deployment and testing without touching real AWS. - Providing a GitHub Actions workflow that runs the full integration test suite on every push.