AWS Architecture Diagrams Guidelines

Lalit Kale Lalit Kale
awsarchitecturebest-practices

AWS architectural diagrams represent AWS resources and other significant objects and their relationships. They communicate the exact blueprints of solutions. Yet many engineers and architects struggle to produce good diagrams — you’ll find many diagrams on the internet that don’t represent meaningful context.

This article provides guidelines on how to draw architectural diagrams, drawn from my own experience and from the wider AWS community.

Why Architectural Diagrams Matter

On the surface, it may look simple to doodle a couple of boxes and arrows. But it is a critical activity from a system perspective. Let’s explore why architectural diagrams are even part of the skill set of any good architect.

Conceptual integrity is one of the key factors for successful architecture. It is the quality of a system where all the concepts and their relationships are consistently applied throughout. 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

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

Formal Architectural Documentation Models

There is no consensus on a single method in the wider software architecture community, but some well-known documentation models exist.

C4 Model

Simon Brown’s C4 model visualizes architecture through Context, Containers, Components, and Code layers. It comes with a recommended set of symbols and encourages text-heavy diagrams. It may or may not be sufficient to describe a full cloud-based architecture — share your experience if you’ve used it for AWS architectures.

4+1 Views

Philippe Kruchten’s 4+1 views represent the system from different stakeholders’ standpoints: logical, development, process, and physical views, each represented by different UML diagrams.

I have been practising 4+1 views for a long time. I use the official AWS icon set to depict the deployment/physical view. AWS has published the official icon set to build architectural diagrams — its use brings consistency among practitioners. The icon set is also available for many diagramming tools.

Logical View Guidelines

  1. Develop your mental model before drawing. Without a mental model, you will fail to draw any meaningful diagram.
  2. Always maintain conceptual integrity. Does the system look cohesive enough to serve its purpose? Do subcomponents have a single purpose of existence?
  3. Use consistent shapes and forms to communicate different subsystems and components.
  4. Consider the C4 model for depicting the logical view.
  5. Do not mix vendor-specific symbols in logical views. Avoid using AWS icons to represent components in logical view diagrams — keep it technology-agnostic.

Physical View (AWS Deployment Diagram) Guidelines

  1. Treat diagrams as testable infrastructure blueprints. Network and deployment diagrams are like actual builds — you can test them before building the real infrastructure. Data flow traceability makes these diagrams a valuable asset.

  2. Consistency is key. Don’t represent an EC2 instance with two different icons. Use the latest official AWS diagramming icon set. There have been three iterations — pick one version and don’t mix symbols from others.

  3. Depict one or at most two flows in a single diagram. Don’t try to showcase every flow and every resource in one diagram.

  4. Don’t copy AWS reference architecture diagrams verbatim. AWS reference architecture diagrams are one-pagers for conversations. Your intent and usage may differ.

  5. Put the title on top. The title should communicate the system and the diagram’s purpose or intent.

  6. Depict the AWS account boundary — even if your solution has a single account. For multi-account scenarios, show only participating accounts; prepare a separate multi-account diagram.

  7. Represent global, regional, and zonal AWS services per their scope. S3 is a global service — it lives inside the account boundary but not within a VPC. A VPC is regional, so it lives inside a region.

  8. Avoid too many lines. When many relationships exist, use color-coding or omit non-critical connections. For example: a blue line for US-East-1 traffic, a red line for EU-West-1.

  9. Don’t assume everyone knows conventions. Private subnets are often shown with a blue background and public subnets with green — but don’t assume your audience knows this. Add a legend.

  10. Maintain diagrams over time. Architectural diagrams are part of your organization’s knowledge base. They lose value if implementation diverges. Invest in periodic reviews.

  11. At minimum, diagram the production environment. Other environments (dev, staging) are optional.

  12. Verify arrow directions to ensure they accurately represent the intended data flow.

  13. Show return traffic with dashed arrows.

  14. Show logical groupings — e.g., a group of Lambdas representing a service, enclosed in a box with dashed lines.

  15. Always peer-review architecture diagrams. If your peers have to ask many questions or need verbal explanation, revisit the diagram.

Closing Thoughts

Architectural diagrams are organizational assets with long-lasting value. Like code, they require maintenance to stay useful. The investment you make in keeping them current pays dividends across teams and time.

References:

  1. Crafting Architectural Diagrams — InfoQ
  2. The Mythical Man-Month: Essays on Software Engineering — Frederick Brooks