Store Checkout State Machine

Store checkout workflow developed using serverless technologies ☁️

📚 Introduction

Workflow orchestration is not a simple task, specially when it comes to event-driven and microservices architectures. AWS Step Functions is a Serverless service that makes it easier to orchestrate complex complex scenarios

The POC in this repository is an book store checkout built on top of AWS Step Functions.

👨🏽‍🔧 Tech stack

🔧 AWS Step Functions - serverless compute service that lets you run code without provisioning or managing servers, creating workload-aware cluster scaling logic, maintaining event integrations, or managing runtimes.
👷🏻 AWS Lambda - serverless compute service that lets you run code without provisioning or managing servers, creating workload-aware cluster scaling logic, maintaining event integrations, or managing runtimes.
🗃️ AWS DynamoDB - fully managed NoSQL database service that provides fast and predictable performance with seamless scalability.
✉️ AWS SNS (Simple Notification Service) - Fully managed pub/sub messaging, SMS, email, and mobile push notifications.
🗞 AWS SQS (Simple Queue Service) - Fully managed message queues for microservices, distributed systems, and serverless applications.
🍃 Serverless Framework - framework that speeds up the development of Serverless cloud-native applications.

🖥️ Features

Check inventory
Calculate order total value
Redeem points
Bill customer
Prepare order
Dispatch order
Refund customer
Restore stock quantity
Restore redeem points

🔗 Step Functions Direct Service integrations

SQS - enqueue order once the costumer is billed
SNS - notify the user by e-mail once the order is dispatched

📌 Design Patterns

Saga Pattern - crucial pattern to rollback the previous states if something fails. For example, if the order fails, the workflow is expected to:
1. Refund the customer
2. Restore the stock quantity
3. Restore redeem points
Callback Pattern - this pattern is used by the direct integration between Step Functions and SQS. Once an order is prepared, it is sent to an SQS queue and the workflow waits for an response from the SQS worker (a Lambda function polling messages from the queue). This worker is responsible for processing the order and communicate back to Step Functions using an Task Token.

✔️ Requirements

Node.js 12.x+
AWS account
AWS IAM user with administrator role and programmatic access (access key id and access secret key)
Serverless Framework CLI globally installed on your machine

⚙️ Deploying the app

The stack deployment only requires a single command thanks to the Serverless Framework.

IMPORTANT: But before deploying the stack, open the serverless.yml file and, under the custom block, replace the sns-email-address with your personal email.

# Clone this repository
git clone https://github.com/eduardo3g/serverless-stepf-store-checkout.git

# Move yourself to the root directory
cd serverless-stepf-store-checkout

# Install the dependencies with NPM
npm install

# Deploy the stack (by detault it'll create a 'dev' stack)
serverless deploy

IMPORTANT: Now that the stack has been deployed, open the email address placed on sns-email-address and click on the confirmation link.

🌱 Seeding the database

Run the following command to seed books and users on DynamoDB tables. You should see a feedback in your terminal to validate if it succeeded or not.

# Generate a .env file on your root directory
npm run exportEnv

# Open the utility folder
cd src/util

# Run the scripts to create 2 books and 2 users on DynamoDB
node seed-books.js
node seed-users.js

🛠 Testing the workflow

After deploying and seeding the DynamoDB tables with fake data, it's time to finally test the Step Functions state machine.

Open the DynamoDB tables (Books and Users) and grab the IDs (bookId and userId attributes).
Open Step Functions and select the StoreCheckoutFlow state machine.
Click on Start execution and pass the following input, replacing the userId and bookId by the ones you created during the database seed process:

{
  "userId": "01G4E1AZW2Q1X3QQEYBACQXMFH",
  "bookId": "01G4E1A9GF5CZWET09RSBR04PV",
  "quantity": 50,
  "redeem": true
}

The execution will start and you'll be able to inspect in real-time the execution progress in the Step Functions UI.

🧪 Test results

The results below are from the perfect scenario. Unexpected errors happen, like not having the book on stock or any other issue. These scenarios are handled by the Saga Pattern implemented in this architecture.

The customer will receive an e-mail with the order data
The stock quantity will be updated on DynamoDB
The user points will be deducted

🐞 Issues

Feel free to create a new issue with an detailed title and description. If you already have a solution to fix the problem, I would be very happy to review your pull request.

🎉 Contributing

I'm highly opened to contributions and would love to review pull requests to make this project even better.

eduardo3g / serverless-stepf-store-checkout