AWS Architecture Diagrams Guidelines

AWS Architectural diagrams represents AWS resources and other significant objects and their relationships. AWS architectural diagrams communicate the exact blueprints of the solutions. Yet, many engineers and architects struggle to produce good diagrams. You will find many diagrams, over the internet, which do not represent the meaningful context.

This article provides guidelines on how to draw the architectural diagrams. These guidelines came from my own experience and many in the AWS community.

Need for Architectural Diagrams

On the surface, it may look simple to doodle a couple of boxes and arrows. But, it is critical activity from the system point of view. So, let's explore why architectural diagrams is even part of the skill set of any good architect.

Conceptual integrity is one of the key factor for successful architecture. It is the quality of a system where all the concepts and their relationships with each other are consistently applied throughout the system. Even if many people work on the system, it would seem cohesive and consistent, as if only one mind was guiding the work.

I will contend that conceptual integrity is the most important consideration in system design. It is better to have a system omit certain anomalous features and improvements, but to reflect one set of design ideas, than to have one that contains many good but independent and uncoordinated ideas. — Frederick Brooks, The Mythical Man-Month: Essays on Software Engineering

Many great technical people are not known for their communication skills. This simple fact hampers the communication of vision. Time is another big factor, due to which conceptual integrity faints away. This signifies the importance of having and maintaining the architectural diagrams.

Formal Architectural Documentation Models

There is a no consensus on one single way or method in the wider software architecture community. But, there are some well-known software architecture documentation models exists. We will explore two of such models in this section.

C4 Model
Simon Brown came up with the C4 model. C4 model visualizes the architecture into a set of Context, Containers, Components, and Code. The C4 model comes with a recommended set of symbols indicating context, containers, components, and code. C4 model also encourages using a lot of text into the diagrams.
I have not used C4 model myself, so could not comment much on it.
I am not sure if C4 model may be enough to describe the whole cloud based architecture – which can meet all stakeholders. So, please do share your AWS architecture diagrams or ways with which you have used C4 model to describe the AWS architectures. This way, I and larger community can gain insights into C4 models and also use it.

4+1 Views
Philippe Kruchten has described 4+1 views in his IEEE article. The views represent the system from the different stakeholders' standpoint. The four views of the model are logical, development, process and physical view. Each view is represented by different types of UML diagrams.

I have been practising 4+1 views from long time. I also have few guidelines for depicting a logical view. Logical view should remain agnostic to any cloud provider or specific technology stack.

I use the official AWS icon set to depict deployment view. AWS has published the official icon set to build architectural diagrams. Its use bring consistency among the different AWS cloud practitioners and users. You can explore the above link and see that the icon set is also made available for many diagramming tools.

Logical View Diagrams Guidelines:

1. Develop your mental model of the solution before making any drawings. Without having a mental model, you will fail to draw any diagram.
2. Always think about maintaining conceptual integrity as solution architect. Does the system look like cohesive enough to serve its purpose? Does the system subcomponents are having single purpose of existence? These are some questions can help you to keep check on conceptual integrity.
3. Use consistent shape and forms to communicate different subsystems and components.
4. You may find C4 model useful to depict the logical view.
5. Use simple shapes to depict components across the system. Do not mix vendor specific symbols to represent the logical view. e.g. using of AWS icons to represent components in logical view diagrams.

Physical View Diagrams Guidelines (AWS Architectural Diagrams Guidelines):

1. Network diagrams and deployment diagrams are like actual builds. You can test them before actually building the real infrastructure. It is a simple but effective method of testing your infrastructure. Data flows or packet flows traceability makes these diagrams a very valuable asset.
2. Consistency in diagrams is key characteristics of a great diagram. e.g. Do not represent EC2 instance, with two different icons. Use the latest official AWS diagramming icon set. There has been three iterations of the icon sets. So if you select one version, please use it without mixing other version icon set symbols.
3. Depict one or most two flows into one single diagram. Do not try to showcase every flow and every resource in one single diagram.
4. AWS reference architectural diagrams reference architecture diagrams are one-pagers for conversations and having something handy. Your intention and usage purpose may vary, so do not copy these style of diagramming all the time.
5. Put the title of the diagram on top. The title should be communicating the system and the diagram's purpose or intent.
6. Depict the AWS account boundary, even if your solution has a single AWS account. For multi-account scenarios, show only participating accounts of the system or subsystem. In such cases, it is better to prepare a separate multi-account diagram.
7. Make sure the diagrams are representing global, regional and zonal AWS services as per their scopes. e.g. S3 is a global service, so it should live inside account but not within VPC. VPC is regional service, hence it should live in a region.
8. Avoid too many lines to represent each relationship or data flow between resources. In such cases, apply different strategy, e.g. representing lines with different colors or not drawing the connections or skipping the connection itself. e.g. blue line represents the traffic flowing from US-East-1 region and red line represents traffic flowing from EU-West-1 region.
9. Do use standard conventions that are set by AWS or used in community. But, do not assume, everyone is aware of such conventions. e.g. private subnets shown with blue background and Public subnets in VPC are always depicted with green background.
10. Architectural diagrams are part of the knowledge base of your organization. It has long-lasting value. Architectural diagrams can lose value, if implementation varies over the period of time. So, please ensure period review and invest time in maintaining the architectural diagrams.
11. At least there should be one diagram representing the exact systems' production environment. If you work with development or test or other more environments, you can also have the diagrams representing them, but it is not necessary.
12. Please do check the arrow directions that your flow is depicting.
13. Show return traffic with intermittent arrows.
14. Show logical grouping, e.g. group of lambdas representing services with a box with intermittent lines.
15. Always do peer-review of system architecture and the diagrams. Make sure, your peers can understand and interpret the diagrams. If your peers have to ask a lot of questions or you need to describe some part of the system more, then you may think to revisit the diagrams.

I am looking forward to enhancing this post and publish update based on the feedback I receive. So, feel free to share your views in comments.

References:

1. https://www.infoq.com/articles/crafting-architectural-diagrams/
2. The Mythical Man-Month: Essays on Software Engineering, Frederick Brooks