Orders and Shipping Status at a Gardening Supplies Mail-Order Shop

Supports a fictional gardening mail-order company in accepting online store orders and updating their status as packing and delivery progress. Orders are checked with the product, delivery and payment services and stored in DynamoDB; delivery and warehouse services read them through API Gateway. Changes go to EventBridge via DynamoDB Streams, and CloudWatch alarms and SNS notify staff of Lambda errors. The business scenario is a fictional example prepared by IceShore, not a real company or system. Source: https://github.com/aws-samples/aws-serverless-ecommerce-platform/tree/3b9ef36dd3e338c8ab697c2bcb1b672e064e303c (Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.; License: MIT No Attribution (MIT-0)). The original files are reproduced without modification.

Actors

Online store front service
Internal delivery and warehouse services
Product service
Delivery service
Payment service
Store-wide event bus
Store system staff

Use cases

Accept orders confirmed by shoppers
Delivery and warehouse services look up orders
Update order status from packing and delivery results
Notify staff of order processing errors

This diagram supports a fictional gardening supplies mail-order company as it accepts orders confirmed on its online store and updates their status as packing and delivery progress. Each order is checked against the product, delivery and payment services before it is stored in Amazon DynamoDB. Order changes are sent through DynamoDB Streams to the store-wide EventBridge event bus. The business scenario is a fictional example prepared by IceShore; the source is orders/template.yaml in aws-samples/aws-serverless-ecommerce-platform (license: MIT-0).

Resources behind order acceptance and status tracking

At the center is the DynamoDB orders table. Its key is orderId, it has a GSI named user on userId and createdDate, and its stream is enabled with NEW_AND_OLD_IMAGES. There are four Lambda functions: CreateOrder accepts orders, GetOrder answers GET /backend/{orderId} on API Gateway (REGIONAL, stage prod), TableUpdate sends table changes as events, and OnEvents updates order status from delivery and warehouse events. Resources outside the template are drawn as external systems: the online store front service that calls CreateOrder, the internal delivery and warehouse services that read orders, the product, delivery and payment services, and the store-wide event bus. Records and events that fail processing go to a dead-letter queue (SQS, defined in a nested stack). CloudWatch alarms notify the store system staff through an SNS topic.

From accepting orders to shipping and error alerts

The diagram has four use cases. In "Accept orders confirmed by shoppers", when a shopper confirms an order, the front service calls the CreateOrder function directly. CreateOrder calls the product, delivery and payment services with POST to check the order, then stores it in the orders table with PutItem. This write triggers the TableUpdate function through DynamoDB Streams, which sends an order event (source: ecommerce.orders) to the event bus. In "Delivery and warehouse services look up orders", GET /backend/{orderId} is called to prepare shipments, and the GetOrder function reads the order with GetItem and returns it. In "Update order status from packing and delivery results", EventBridge rules deliver delivery events (DeliveryCompleted/DeliveryFailed) and warehouse events (PackageCreated/PackagingFailed) to the OnEvents function. OnEvents updates the order status. Its IAM policy limits the attributes it can read and write to orderId, products and status. TableUpdate then sends this change as an order event as well. In "Notify staff of order processing errors", CloudWatch alarms notify the SNS topic when a threshold is crossed. The template's alarms cover Lambda errors and throttles, API Gateway 4XX, 5XX and latency, DynamoDB errors and anomaly detection on order counts, among others. The diagram uses LambdaErrorsAlarm as the representative starting point. The order volume of 15,000 to 60,000 a month and the spring peak are assumptions for this fictional scenario.

Source IaC (orders/template.yaml)

The source is orders/template.yaml from aws-samples/aws-serverless-ecommerce-platform (commit 3b9ef36dd3e338c8ab697c2bcb1b672e064e303c, MIT-0). It is a CloudFormation template in SAM format that uses Transform: AWS::Serverless-2016-10-31. The main resource types are: AWS::DynamoDB::Table (Table); AWS::Serverless::Function (CreateOrderFunction, GetOrderFunction, TableUpdateFunction, OnEventsFunction); AWS::Serverless::Api (Api); AWS::CloudFormation::Stack (DeadLetterQueue, referencing shared/templates/dlq.yaml); AWS::SNS::Topic (AlarmTopic); AWS::CloudWatch::Alarm (various alarms); AWS::CloudWatch::AnomalyDetector; AWS::CloudWatch::Dashboard; AWS::Logs::LogGroup; and AWS::SSM::Parameter. The template receives the URLs and ARNs of the external APIs, and the event bus name and ARN, through SSM parameters. It also publishes the table name, the CreateOrder function ARN, and the API URL and ARN as SSM parameters.

How this diagram was made, and the business scenario

This diagram was created from the IaC above in a public repository. An AI first read the template and wrote the diagram description (ADL) through IceShore's MCP (Model Context Protocol) server. IceShore rendered the diagram from that description. Callers that do not appear in the template (the front service and the internal delivery and warehouse services) and the store system staff who receive notifications are described as actors in the ADL: callers as external systems, staff as people. SNS subscriptions are assumed to be configured outside the template. The original template is the orders service of a general e-commerce platform. The gardening mail-order scenario is a fictional example prepared by IceShore, not a real company or system.

FAQ

Can a CloudFormation template that uses SAM (AWS::Serverless::Function, etc.) be turned into an architecture diagram?

Yes. The template behind this diagram, orders/template.yaml, is in SAM format with Transform: AWS::Serverless-2016-10-31. The diagram shows how the functions, the API, the stream and the event rules connect, based on the AWS::Serverless::Function and AWS::Serverless::Api resources and their event settings (Api, DynamoDB, CloudWatchEvent).

Why do the product, delivery and payment services and the event bus, which the template does not define, appear in the diagram?

They are in other stacks. This template receives their URLs and ARNs through SSM parameters (AWS::SSM::Parameter::Value<String>). The CreateOrder function's IAM policy also allows execute-api:Invoke (POST) on each API, so the diagram shows them as external systems. In this scenario, they are the company's own services for checking gardening product details and prices, delivery addresses and shipping fees, and payments.

What goes to the dead-letter queue?

The template sends two kinds of failures there: DynamoDB stream records that the TableUpdate function fails to process (its OnFailure destination), and events whose asynchronous invocation of OnEvents fails (EventInvokeConfig OnFailure). The queue itself is defined in a nested stack (shared/templates/dlq.yaml). That file is outside the source template, so its contents are not drawn.

Source: aws-samples/aws-serverless-ecommerce-platform（MIT-0）

Load your IaC to get a diagram like this for your own system. What is IceShore