Sequence Diagrams enrich your understanding of distributed architectures
AWS Architecture BlogSequence Diagrams enrich your understanding of distributed architecturesby Kevin Hakanson | on19 AUG 2022| inAmazon API Gateway,Amazon CloudFront,Architecture,AWS Lambda,Serverless|Permalink|ShareArchitecture diagrams visually communicate and document the high-level design of a solution. As the level of detail increases, so does the diagram’s size, density, and layout complexity. Using Sequence Diagrams, you can explore additional usage scenarios and enrich your understanding of the distributed architecture while continuing to communicate visually.This post takes a sample architecture and iteratively builds out a set of Sequence Diagrams. Each diagram adds to the vocabulary and graphical notation of Sequence Diagrams, then shows how the diagram deepened understanding of the architecture. All diagrams in this post were rendered from a text-based domain specific language using a diagrams-as-code tool instead of being drawn with graphical diagramming software.Sample architectureThe architecture is based onImplementing header-based API Gateway versioning with Amazon CloudFrontfrom theAWS Compute Blog, which uses theAWS Lambda@Edgefeature to dynamically route the request to the targeted API version.Amazon API Gatewayis a fully managed service that makes it easier for developers to create, publish, maintain, monitor, and secure APIs at any scale.Amazon CloudFrontis a global content delivery network (CDN) service built for high-speed, low-latency performance, security, and developer ease-of-use. Lambda@Edge lets you run functions that customize the content that CloudFront delivers.The numbered labels in Figure 1 correspond to the following text descriptions:User sends an HTTP request to CloudFront, including a version header.CloudFront invokes the Lambda@Edge function for the Origin Request event.The function matches the header value to data fetched from anAmazon DynamoDBtable, then modifies the Host header and path of the request and returns it to CloudFront.CloudFront routes the HTTP request to the matching API Gateway.Figure 1 architecture diagram is a free-form mixture between a structure diagram and a behavior diagram. It includes structural aspects from a high-level Deployment Diagram, which depicts network connections between AWS services. It also demonstrates behavioral aspects from a Communication Diagram, which uses messages represented by arrows labeled with chronological numbers.Figure 1. High-level architecture diagramSequence DiagramsSequence Diagrams are part of a subset of behavior diagrams known as interaction diagrams, which emphasis control and data flow. Sequence Diagrams model the ordered logic of usage scenarios in a consistent visual manner and capture detailed behaviors. I use this diagram type for analysis and design purposes and to validate my assumptions about data flows in distributed architectures. Let’s investigate the system use case where the API is called without a header indicating the requested version using a Sequence Diagram.Examining the system use caseIn Figure 2, User, Web Distribution, and Origin Request are each actors or system participants. The parallel vertical lines underneath these participants arelifelines. The horizontal arrows between participants aremessages, with the arrowhead indicating message direction. Messages are arranged in time sequence from top to bottom. The dashed lines represent reply messages. The text inside guillemets («like this») indicate astereotype, which refines the meaning of a model element. The rectangle with the bent upper-right corner is anotecontaining additional useful information.Figure 2. Missing accept-version headerThe message from User to Web Distribution lacks any HTTP header that indicates the version, which precipitates the choice of Accept-Version for this name. The return message requires a decision about HTTP status code for this error case (400). The interaction with the Origin Request prompts a selection ofLambda runtimes(nodejs14.x) and understanding the programming model forgenerating an HTTP responsefor this request.Designing the interactionNext, let’s design the interaction when the Accept-Version header is present, but the corresponding value is not found in the Version Mappings table.Figure 3 adds new notation to the diagram. The rectangle with “opt” in the upper-left corner and bolded text inside square brackets is aninteraction fragment. The “opt” indicates this operation is an option based on theconstraint(orguard) that “version mappings not cached” is true.Figure 3. API version not foundADynamoDB scan operationon every request consumes table read capacity. Caching Version Mappings data inside the Lambda@Edge function’s memory optimizes foron-demand capacity mode. The «on-demand» stereotype on the DynamoDB participant succinctly communicates this decision. The “API V3 not found” note on Figure 3 provides clarity to the reader. The HTTP status code for this error case is decided as 404 with a custom description of “API Version Not Found.”Now, let’s design the interaction where the API version is found and the caller receives a successful response.Figure 4 is similar to Figure 3 up until the note, which now indicates “API V1 found.” Consulting the documentation forWriting functions for Lambda@Edge, the request event is updated with the HTTP Host header and path for the “API V1” Amazon API Gateway.Figure 4. API version foundInstead of three separate diagrams for these individual scenarios, a single, combined diagram can represent the entire set of use cases. Figure 5 includes two new “alt” interaction fragments that represent choices of alternative behaviors.The first “alt” has a guard of “missing Accept-Version header” mapping to our Figure 2 use case. The “else” guard encompasses the remaining use cases containing a second “alt” splitting where Figure 3 and Figure 4 diverge. That “version not found” guard is the Figure 3 use case returning the 404, while that “else” guard is the Figure 4 success condition. The added notes improve visual clarity.Figure 5. Header-based API Gateway versioning with CloudFrontDiagrams as codeAfter diagrams are created, the next question is where to save them and how to keep them updated. Because diagrams-as-code use text-based files, they can be stored and versioned in the same source control system as application code. Also consider anarchitectural decision record (ADR) processto document and communicate architecturally significant decisions. Then as application code is updated, team members can revise both the ADR narrative and the text-based diagram source. Up-to-date documentation is important for operationally supporting production deployments, and these diagrams quickly provide a visual understanding of system component interactions.ConclusionThis post started with a high-level architecture diagram and ended with an additional Sequence Diagram that captures multiple usage scenarios. This improved understanding of the system design across success and error use cases. Focusing on system interactions prior to coding facilitates the interface definition and emergent properties discovery, before thinking in terms of programming language specific constructs and SDKs.Experiment to see if Sequence Diagrams improve the analysis and design phase of your next project. View additional examples of diagrams-as-code from theAWS Icons for PlantUMLGitHub repository. TheWorkload Discovery on AWSsolution can even build detailed architecture diagrams of your workloads based on live data from AWS.For vetted architecture solutions and reference architecture diagrams, visit theAWS Architecture Center. For more serverless learning resources, visitServerless Land.Related informationTheUnified Modeling Language specificationprovides the full definition of Sequence Diagrams. This includes notations for additional interaction frame operators, using open arrow heads to represent asynchronous messages, and more.Diagrams were created for this blog post usingPlantUMLand theAWS Icons for PlantUML. PlantUML integrates with IDEs, wikis, and other external tools. PlantUML is distributed under multiple open-source licenses, allowing local server rendering for diagrams containing sensitive information. AWS Icons for PlantUML include the officialAWS Architecture Icons.Kevin HakansonKevin Hakanson is a Sr. Solutions Architect for AWS World Wide Public Sector based in Minnesota. He works with EdTech and GovTech customers to ideate, design, validate, and launch products using cloud-native technologies and modern development practices. When not staring at a computer screen, he is probably staring at another screen, either watching TV or playing video games with his family.
Architecture diagrams visually communicate and document the high-level design of a solution. As the level of detail increases, so does the diagram’s size, density, and layout complexity. Using Sequence Diagrams, you can explore additional usage scenarios and enrich your understanding of the distributed architecture while continuing to communicate visually. This post takes a sample architecture […]
Kevin Hakanson
Amazon API Gateway Amazon CloudFront Architecture AWS Lambda Serverless