jkahn117 / eventdriven-frontend-patterns

Sample code accompanying Goto EDA Day 2024 talk - Patterns for building event-driven web and mobile app backends

Patterns for building event-driven web and mobile app backends

User interfaces by their nature are event driven - interactions trigger events that drive the application. But integrations between frontend and backend are often built synchronously using a request/response pattern. The samples in this repository explore patterns to enable asynchronous, event-driven integrations with the frontend. These real-world patterns bring the agility and responsiveness of EDA across client-server interactions.

Patterns in this repository accompany EDA Day London 2024.

Table of Contents

1. Getting Started
   • Prerequisites
2. Deploy patterns
   • Prerequisites
   • Option 1: Deploy all resources at once
   • Option 2: Deploy pattern independently
3. Available patterns
4. Starting the frontend
5. Roadmap
6. Authors

Getting started

To get started, clone this repository:

$ git clone https://github.com/aws-samples/eventdriven-frontends

Prerequisites

Patterns are deployed to the AWS Region of your choice. Note that all services must be available in the selected Region:

1. Select your preferred AWS Region.
2. Install AWS SAM CLI. All deployments are via SAM CLI.
3. Install Node.js and esbuild or build with the --use-container option.

Deploy patterns

Option 1: Deploy all resources at once

All shared resources and patterns will be deployed using a similar CloudFormation / AWS SAM template. Patterns are deployed as nested stacks. Note that this option can take a few minutes to complete.

To deploy all shared resources and patterns:

sam build && sam deploy --guided

Respond to the prompts:

• Stack Name [patterns-eventdriven-frontends-shared]: enter your own stack name or accept default
• AWS Region [us-west-2]: select a Region, any will work
• Parameter ProjectName [patterns-eventdriven-frontends]: keep the default
• Parameter IoTCoreEndpoint []: see below
• Parameter WebPushPublicToken []: see below
• Parameter WebPushPrivateToken []: see below
• Confirm changes before deploy [y/N]: N
• Allow SAM CLI IAM role creation [Y/n]: Y
• Disable rollback [y/N]: N
• Save arguments to configuration file [Y/n]: Y
• SAM configuration file [samconfig.toml]: accept default
• SAM configuration environment [default]: accept default

IoTCoreEndpoint

IoT Core provides an endpoint that is unique to your account and region. To find the endpoint for a region, use the describe-endpoint CLI command:

aws iot describe-endpoint --endpoint-type iot:Data-ATS

You can also find the endpoint in the AWS IoT Core console settings page. Look for Endpoint in the Device data endpoint panel. Make note of the endpoint, we refer to it as mqttEndpoint moving forward.

WebPushPublicToken, WebPushPrivateToken

Web push notifications require creation of VAPID keys to uniquely identify the sender. VAPID keys can be generated by visiting https://web-push-codelab.glitch.me/ and noting the public and private keys. You will need these keys to deploy the push stack and to configure the frontend.

Wait a few minutes while the shared resources are deployed. Make note of all outputs as you will need them to configure the frontend web application.

We encourage you to review the README for all patterns you deploy for further details.

---

Option 2: Deploy pattern independently

To deploy one or more patterns separate from the others,

Step 1: Deploying shared resources

Before deploying any patterns, you must deploy shared resources for the project. Shared AWS resources include an Amazon EventBridge event bus and an AWS Lambda function to generate mock data.

To deploy the shared resources:

cd shared

sam build && sam deploy --guided

Respond to the prompts:

• Stack Name [patterns-eventdriven-frontends-shared]: enter your own stack name or accept default
• AWS Region [us-west-2]: select a Region, any will work
• Parameter ProjectName [patterns-eventdriven-frontends]: keep the default
• Confirm changes before deploy [y/N]: N
• Allow SAM CLI IAM role creation [Y/n]: Y
• Disable rollback [y/N]: N
• Save arguments to configuration file [Y/n]: Y
• SAM configuration file [samconfig.toml]: accept default
• SAM configuration environment [default]: accept default

Wait a few minutes while the shared resources are deployed. Make note of the ApiEndpoint output as you will need it to configure the frontend web application.

Step 2: Deploy patterns

The /patterns in this project directory are designed so that they can be deployed indepdently of each other. All are dependent on the shared resources you deployed in step 1, none are dependent on another pattern.

Deployment instructions for the patterns are mostly the same, though the IoT Core and Push patterns require additional information at deployment time. Details are found in the README for those patterns.

cd shared

sam build && sam deploy --guided

NOTE: Lambda functions included in this project are targetted for the arm64 architecture. If your development machine is on an Intel processor, you will need to (1) install Docker and (2) add a flag in the build step sam build --use-container && sam deploy --guided.

Respond to the prompts:

• Stack Name [patterns-eventdriven-frontends-pattern]: enter your own stack name or accept default
• AWS Region [us-west-2]: select a Region, any will work
• Parameter ProjectName [patterns-eventdriven-frontends]: keep the default or provide your own name
• Confirm changes before deploy [y/N]: N
• Allow SAM CLI IAM role creation [Y/n]: Y
• Disable rollback [y/N]: N
• Save arguments to configuration file [Y/n]: Y
• SAM configuration file [samconfig.toml]: accept default
• SAM configuration environment [default]: accept default

After deploying the patterns, you can configure and start the frontend demo application.

We encourage you to review the README for all patterns you deploy for further details.

Available patterns

• Pattern #1: AWS AppSync + DyanmoDB Stream
• Pattern #2: AWS AppSync + Amazon EventBridge
• Pattern #3: Amazon API Gateway WebSockets
• Pattern #4: AWS IoT Core
• Web Push

Starting the frontend

The frontend included in this project is built using React.js. Other web and mobile application platforms could also be used.

Please note that some implementation decisions in the frontend were made to accommodate multiple patterns on the same screen, at the same time. We generally recommend the AWS Amplify client libraries to integrate your frontend applications with AWS resources used in the project (e.g., Amazon API Gateway, AWS AppSync, and AWS IoT Core).

cd frontend

Rename frontend/src/appconfig.js.sample to frontend/src/appconfig.js.

Open frontend/src/appconfig.js in your editor of choice. Update the configuration using outputs from the shared and pattern stacks.

const config = {
  region: "", // AWS region you deployed to
  identityPoolId: "", // `IdentityPoolId` from shared stack output
  sharedEndpoint: "", // `ApiEndpoint` from shared stack output, you must include `/Prod` at end
  mqttEndpoint: "", // IoT Core endpoint for your account, see pattern 4 README
  pattern1: {
    endpoint: "" // `GraphQLEndpoint` from pattern 1 stack output
  },
  pattern2: {
    endpoint: "" // `GraphQLEndpoint` from pattern 2 stack output
  },
  pattern3: {
    endpoint: "" // `WebSocketEndpoint` from pattern 3 stack output, you must include `wss://` at start and `/prod` at end
  },
  push: {
    applicationServerKey: "" // your public key for web push, see push pattern README for details
  },
  chat: {
    endpoint: "" // `GraphQLEndpoint` from long-running stack output
  }
};

Save your changes.

Then install dependencies and start the development server.

npm install

npm run dev

Navigate to http://localhost:5173 in your browser.

Roadmap

• Add custom resource to retrieve IoT Core endpoint instead of passing parameter
• Move handleOrderEvents.js, order.js, and order.d.ts to a shared directory

Authors

• Josh Kahn - initial work

Need to deploy shared before push When push is deployed, does it do the API GW deployment?