AWS AI Stack - A ready-to-use, full-stack boilerplate project for building serverless AI applications on AWS. A great fit for those seeking a trusted AWS foundation for AI apps and access to powerful LLM models via Bedrock that keep your app's data separate from model providers.
View the Live Demo - awsaistack.com
Use this as a boilerplate project to create an AI Chat bot, authentication services, business logic, async workers, all on AWS Lambda, API Gateway, DynamoDB, and EventBridge.
This is a true serverless architecture, so you only pay for what you use, not for idle time. Some services, like DynamoDB, or AWS Bedrock trained models, may have additional storage costs.
This project is structured as a monorepo with multiple services. Each service has its own file, so you must install the dependencies for each service. Running in the root directory will install the dependencies for all services.
Setup AWS Credentials
If you haven't already, setup your AWS Credentials. You can follow the AWS Credentials doc for step-by-step instructions.
This example requires the AWS Bedrock Model to be enabled. By default, AWS does not enable these models, you must go to the AWS Console and individually request access to the AI Models.
There is no cost to enable the models, but you must request access to use them.
Upon request, it may take a few minutes for AWS to enable the model. Once they are enabled, you will receive an email from AWS confirming the model is enabled.
Some users have reported issues with getting models enabled on AWS Bedrock. Make sure you have sufficient permissions in AWS to enable the models first. Often, AWS accounts that are new or have not historically had a monthly invoice over a few dollars may require contacting AWS to enable models.
Now you are ready to deploy the services. This will deploy all the services to your AWS account. You can deploy the services to the stage, which is the default stage for development.
Deploy the services
At this point the service is live. When running the command, you will see the output of the services that were deployed. One of those services is the service, which is the website service. To view the app, go to the URL in the section for the service.
Once you start developing it is easier to run the service locally for faster iteration. We recommend using Serverless Dev Mode. You can run Dev Mode for individual services. This emulates Lambda locally and proxies requests to the real service.
Once done, you can redeploy individual services using the command with the service name.
The service is a static website that is served from an AWS Lambda function. As such, it can run locally without needing to use Dev Mode. However, it has a dependency on the AI Chat service and the Auth service, so you must configure environment variables locally.
Now that the app is up and running in a development environment, lets get it ready for production by setting up a custom domain name, and setting a new shared secret for JWT token authentication.
This project is configured to use custom domain names. For non deployments this is disabled. Deployments to are designed to use a custom domain name and require additional setup:
Register the domain name & create a Route53 hosted zone
If you haven't already, register a domain name, and create a Route53 hosted zone for the domain name.
https://us-east-1.console.aws.amazon.com/route53/v2/hostedzones?region=us-east-1#
Create a Certificate in AWS Certificate Manager
A Certificate is required in order to use SSL () with a custom domain name. AWS Certificate Manager (ACM) provides free SSL certificates for use with your custom domain name. A certificate must first be requested, which requires verification, and may take a few minutes.
https://us-east-1.console.aws.amazon.com/acm/home?region=us-east-1#/certificates/list
After you have created the certificate, you must validate the certificate by following the instructions in the AWS Console. This may require adding a CNAME record to your DNS provider.
This example uses a Certificate with the following full qualified domain names:
Authentication is implemented using JWT tokens. A shared secret is used to sign the JWT tokens when a user logs in. The secret is also used to verify the JWT tokens when a user makes a request to the API. It is important that this secret is kept secure and not shared.
Once you've setup the custom domain name (optional), and created the secret, you are ready to deploy the service to prod.
Now you can use the service by visiting your domain name, or https://awsaistack.com. This uses the Auth service to login and register users, the AI Chat service to interact with the AI Chat bot.
This example uses serverless services like AWS Lambda, API Gateway, DynamoDB, EventBridge, and CloudFront. These services are designed to scale with usage, and you only pay for what you use. This means you do not pay for idle, and only pay for the resources you consume. If you have 0 usage, you will have $0 cost.
If you are using the custom domain names, it will require Route53 which has a fixed monthly cost.
This example uses Serverless Compose to share configuration across all services.
It defines the global parameters in the file under and . These parameters are used across all services to provide shared configuration.
It also uses CloudFormation from services to set parameters on other services. For example, the service publishes the CloudFormation Output , which is used by the website service.
Using Serverless Compose also allows you to deploy all services with a single command, .
The service contains a shared client library that is used by the other services to validate the JWT token. This library is defined as an NPM package and is used by the and services and included using relative paths in the file.
The service is an Express.js-based API service that provides login and registration endpoints. It uses a DynamoDB table to store user information and uses JWT tokens for authentication.
Upon login or registration, the service returns a JWT token. These APIs are used by the website service to authenticate users. The token is stored in localstorage and is used to authenticate requests to the and services.
The service uses AWS Lambda Function URLs instead of API Gateway, in order to support streaming responses. As such, it uses the class from to validate the JWT token, instead of using an API Gateway authorizer.
The service also publishes the CloudFormation Output , which is used by the website service to make requests to the service.
In most cases APIs on AWS Lambda use the API Gateway to expose the API. However, the service uses Lambda Function URLs instead of API Gateway, in order to support streaming responses as streaming responses are not supported by API Gateway.
Since the service does not use API Gateway, it does not support custom domain names natively. Instead, it uses a CloudFront Distribution to support a custom domain name.
To provide the AI Chat functionality, the service uses the AWS Bedrock Models service to interact with the AI Chat bot. The requests from the frontend (via the API) are sent to the AWS Bedrock Models service, and the streaming response from Bedrock is sent back to the frontend via the streaming response.
The AWS Bedrock AI Model is selected using the parameter in the file.
The AI Chat service also implements a simple throttling schema to limit cost exposure when using AWS Bedrock. It implements a monthly limit for the number of requests per user and a global monthly limit for all users. It uses a DynamoDB Table to persist the request counts and other AI usage metrics.
The inline comments provider more details on this mechanism as well as ways to customize it to use other metrics, like token usage.
The website service is a simple Lambda function which uses Express to serve static assets. The service uses the plugin to run the command to build the website before deploying.
The build command uses the parameters to set the environment variables, which are used in the React app to configure the API URLs.
The frontend website is built using React. It uses the service to login and register uses, and uses the to interact with the AI Chat bot API.
This is an Express.js-based API service that provides a placeholder for your business logic. It is configured to use the same custom domain name as the service, but with a different base path ().
The endpoints are protected using the middleware, which uses the JWT token provided by the service to authenticate the user.
This is a placeholder function for your business logic for processing asynchronous events. It subscribes to events on the EventBridge and processes the events.
Currently this subscribes to the event, which is published by the service when a user registers.
Both the Business Worker and the Auth service therefore depend on the EventBridge which is provisioned in the service.
The services which use API Gateway use the plugin to setup the custom domain name. More details about the plugin can be found on the serverless-domain-manager plugin page.
The service uses Lambda Function URLs instead of API Gateway, so custom domain name is supported by creating a CloudFront Distribution with the custom domain name and the Lambda Function URL as the origin.
The and APIs both use the same custom domain name. Instead of sharing an API Gateway, they are configured to use the same domain name with different base paths, one for each service.
Below are a few simple API requests using the command.
If you have installed, you can wrap the login request in a command to set the token as an environment variable so you can use the token in subsequent requests.
You can also use the Chat API directly; however, the response payload is a a stream of JSON objects containing the response and other metadata. Each buffer may also contain multiple JSON objects.
This endpoint is authenticated and requires the JWT token from the login API.
This endpoint is also authenticated and requires the JWT token from the login API. The response is a simple message.
The Chat API uses CloudFront Distributions to add support for custom domain names to the AWS Lambda Function URL, as it is not natively supported. The Auth & Business APIs on the other hand use API Gateway which supports custom domain names natively. However, an API Gateway and a CloudFront Distribution do not support using the same hostname as they both require a CNAME record.
For these two services to share the same domain name, consider using the CloudFront distribution to proxy the API Gateway requests. This would allow both services to use the same domain name, and would also allow the Chat API to use the same domain name as the other services.
In this configuration, the Auth and Business APIs use the paths and respectively on . The Custom Domain Name Path Mapping was used in the Custom Domain Name support in API Gateway to use the same domain name but shared across multiple API Gateway instances.
Alternatively, you you can use a single API Gateway and map the paths to the respective services. This would allow you to use the same domain name for multiple services, and would also allow you to use the same authorizer for all the services. However, sharing an API Gateway instance may have performance implications at scale, which is why this example uses separate API Gateway instances for each service.
The , , and all validate the user input, and in the case of use Zod to validate the schema. Consider including schema validation on all API requests using a library like Zod, and/or Express.js middleware.
This example, for simplicity, hosts the static assets from an AWS Lambda Function. This is not recommended for production, and you should consider using a static website hosting service like S3 or CloudFront to host your website. Consider using one of the following plugins to deploy your website:
This example uses a custom authorization method using JWT tokens for the service, which doesn't use API Gateway.
The is based on Express.js and uses the method in the to validate the JWT token.
API Gateway supports Lambda Authorizers which can be used to validate JWT tokens before the request is passed to the Lambda Function. This is a more robust solution than the custom method used in this example, and should be considered for production services. This method will not work for the service as it does not use API Gateway.
Using Github Actions this example deploys all the services using Serverless Compose. This ensures that any changes to the individual services or the will reevaluate the interdependent parameters. However, all services are redeployed on any change in the repo, which may not be necessary.
Consider using a more fine-grained approach to deploying services, such as only deploying the services that have changed by using the command.
