github.com/aws-samples/aws-bookstore-demo-app @v1.1.0

AWS Bookstore Demo App

AWS Bookstore Demo App is a full-stack sample web application that creates a storefront (and backend) for customers to shop for fictitious books. The entire application can be created with a single CloudFormation template. Try out the deployed application here!

You can browse and search for books, look at recommendations and best sellers, manage your cart, checkout, view your orders, and more. Get started with building your own below!  

License Summary

This sample code is made available under a modified MIT license. See the LICENSE file.

 

Outline

• Overview
• Instructions
• Getting started
• Cleaning up
• Architecture
• Implementation details
• Amazon DynamoDB
• Amazon API Gateway
• AWS Lambda
• Amazon ElastiCache for Redis
• Amazon Neptune
• Amazon ElasticSearch
• AWS IAM
• Amazon Cognito
• Amazon Cloudfront and Amazon S3
• Amazon VPC
• Amazon Cloudwatch
• AWS CodeCommit, AWS CodePipeline, AWS CodeBuild
• Running your web application locally
• Considerations for demo purposes
• Known limitations
• Additions, forks, and contributions
• Questions and contact

 

Overview

The goal of AWS Bookstore Demo App is to provide a fully-functional web application that utilizes multiple purpose-built AWS databases and native AWS components like Amazon API Gateway and AWS CodePipeline. Increasingly, modern web apps are built using a multitude of different databases. Developers break their large applications into individual components and select the best database for each job. Let's consider AWS Bookstore Demo App as an example. The app contains multiple experiences such a shopping cart, product search, recommendations, and a top sellers list. For each of these use cases, the app makes use of a purpose-built database so the developer never has to compromise on functionality, performance, or scale.

The provided CloudFormation template automates the entire creation and deployment of AWS Bookstore Demo App. The template includes the following components:

Database components

• Product catalog/shopping cart - Amazon DynamoDB offers fast, predictable performance for the key-value lookups needed in the product catalog, as well as the shopping cart and order history. In this implementation, we have unique identifiers, titles, descriptions, quantities, locations, and price.
• Search - Amazon Elasticsearch Service enables full-text search for our storefront, enabling users to find products based on a variety of terms including author, title, and category.
• Recommendations - Amazon Neptune provides social recommendations based on what user's friends have purchased, scaling as the storefront grows with more products, pages, and users.
• Top sellers list - Amazon ElastiCache for Redis reads order information from Amazon DynamoDB Streams, creating a leaderboard of the “Top 20” purchased or rated books.

Application components

• Serverless service backend – Amazon API Gateway powers the interface layer between the frontend and backend, and invokes serverless compute with AWS Lambda.
• Web application blueprint – We include a React web application pre-integrated out-of-the-box with tools such as React Bootstrap, Redux, React Router, internationalization, and more.

Infrastructure components

• Continuous deployment code pipeline – AWS CodePipeline and AWS CodeBuild help you build, test, and release your application code.
• Serverless web application – Amazon CloudFront and Amazon S3 provide a globally-distributed application.

You can choose to customize the template to create your own bookstore, modify it to make a different type of store, or change it to make a completely different type of web application.

AWS Bookstore Demo App is built on-top of AWS Full-Stack Template, which provides the foundational services, components, and plumbing needed to get a basic web application up and running. Users can build on top of AWS Full-Stack Template to create any application they envision, whether a travel booking tool, a blog, or another web app. This AWS Bookstore Demo App is just one example of what you can create using AWS Full-Stack Template.

Watch the recorded talk and demo here.  

---

 

Instructions

IMPORTANT NOTE*: Creating this demo application in your AWS account will create and consume AWS resources, which will cost money. We estimate that running this demo application will cost ~$0.45/hour* with light usage. Be sure to shut down/remove all resources once you are finished to avoid ongoing charges to your AWS account (see instructions on cleaning up/tear down below).

 

Getting started

To get AWS Bookstore Demo App up and running in your own AWS account, follow these steps (if you do not have an AWS account, please see How do I create and activate a new Amazon Web Services account?):

1. Log into the AWS console if you are not already.
   Note: If you are logged in as an IAM user, ensure your account has permissions to create and manage the necessary resources and components for this application.
2. Choose one of the Launch Stack buttons below for your desired AWS region to open the AWS CloudFormation console and create a new stack. AWS Bookstore Demo App is supported in the following regions:

Region name	Region code	Launch
US East (N. Virginia)	us-east-1
US West (Oregon)	us-west-2
EU (Ireland)	eu-west-1
EU (Frankfurt)	eu-central-1

1. Continue through the CloudFormation wizard steps
   1. Name your stack, e.g. MyBookstore
   2. Provide a project name (must be lowercase, letters only, and under twelve (12) characters). This is used when naming your resources, e.g. tables, search domain, etc.
   3. After reviewing, check the blue box for creating IAM resources.
2. Choose Create stack. This will take ~20 minutes to complete.
3. Once the CloudFormation deployment is complete, check the status of the build in the CodePipeline console and ensure it has succeeded.
4. Sign into your application
   1. The output of the CloudFormation stack creation will provide a CloudFront URL (in the Outputs table of your stack details page). Click the link or copy and paste the CloudFront URL into your browser.
   2. You can sign into your application by registering an email address and a password. Choose Sign up to explore the demo to register. The registration/login experience is run in your AWS account, and the supplied credentials are stored in Amazon Cognito. Note: given that this is a demo application, we highly suggest that you do not use an email and password combination that you use for other purposes (such as an AWS account, email, or e-commerce site).
   3. Once you provide your credentials, you will receive a verification code at the email address you provided. Upon entering this verification code, you will be signed into the application.

 

Advanced: The source CloudFormation template is available here. If you want to maintain low latency for your app, this deeplink will create an identical stack, but with additional triggers to keep the Lamdba functions "warm" (CloudFormation template here). For more information, see the Considerations for demo purposes section.

 

Cleaning up

To tear down your application and remove all resources associated with AWS Bookstore Demo App, follow these steps:

1. Log into the Amazon S3 Console and delete the buckets created for the demo app.
2. There should be two buckets created for AWS Bookstore Demo App. The buckets will be titled "X" and "X-pipeline", where "X" is the name you specified in the CloudFormation wizard under the AssetsBucketName parameter.
3. Note: Please be very careful to only delete the buckets associated with this app that you are absolutely sure you want to delete.
4. Log into the AWS CloudFormation Console and find the stack you created for the demo app
5. Delete the stack

Remember to shut down/remove all related resources once you are finished to avoid ongoing charges to your AWS account.

 

---

 

Architecture

Summary diagram

 

High-level, end-to-end diagram

 

Frontend

Build artifacts are stored in a S3 bucket where web application assets are maintained (like book cover photos, web graphics, etc.). Amazon CloudFront caches the frontend content from S3, presenting the application to the user via a CloudFront distribution. The frontend interacts with Amazon Cognito and Amazon API Gateway only. Amazon Cognito is used for all authentication requests, whereas API Gateway (and Lambda) is used for all API calls interacting across DynamoDB, Elasticsearch, ElastiCache, and Neptune.

Backend

The core of the backend infrastructure consists of Amazon Cognito, Amazon DynamoDB, AWS Lambda, and Amazon API Gateway. The application leverages Amazon Cognito for user authentication, and Amazon DynamoDB to store all of the data for books, orders, and the checkout cart. As books and orders are added, Amazon DynamoDB Streams push updates to AWS Lambda functions that update the Amazon Elasticsearch cluster and Amazon ElasticCache for Redis cluster. Amazon Elasticsearch powers search functionality for books, and Amazon Neptune stores information on a user's social graph and book purchases to power recommendations. Amazon ElasticCache for Redis powers the books leaderboard.

 

Developer Tools

The code is hosted in AWS CodeCommit. AWS CodePipeline builds the web application using AWS CodeBuild. After successfully building, CodeBuild copies the build artifacts into a S3 bucket where the web application assets are maintained (like book cover photos, web graphics, etc.). Along with uploading to Amazon S3, CodeBuild invalidates the cache so users always see the latest experience when accessing the storefront through the Amazon CloudFront distribution. AWS CodeCommit. AWS CodePipeline, and AWS CodeBuild are used in the deployment and update processes only, not while the application is in a steady-state of use.

 

---

 

Implementation details

Note: The provided CloudFormation template contains only a portion of the resources needed to create and run the application. There are web assets (images, etc.), Lambda functions, and other resources called from the template to create the full experience. These resources are stored in a public-facing S3 bucket and referenced in the template.

 

Amazon DynamoDB

The backend of AWS Bookstore Demo App leverages Amazon DynamoDB to enable dynamic scaling and the ability to add features as we rapidly improve our e-commerce application. The application create three tables in DynamoDB: Books, Orders, and Cart. DynamoDB's primary key consists of a partition (hash) key and an optional sort (range) key. The primary key (partition and sort key together) must be unique.

Books Table:

```js BooksTable { id: string (primary partition key) author: string category: string (index, GSI) cover: string (url to s3 file