AWS Resource Diagram Conventions

Conventions for creating AWS infrastructure diagrams in PlantUML within Arda design documents. These rules extend the general PlantUML Guide with AWS-specific guidance derived from the AWS Architecture Icons program and the awslabs/aws-icons-for-plantuml library.

Library Setup

Use the official AWS Icons for PlantUML library. Pin to a specific version to ensure reproducible rendering.

PlantUML diagram

All Arda diagrams must use v20.0 (aligned with AWS Architecture Icons Release 20, February 2025). Do not use main or latest — diagram rendering must be deterministic. The full symbol catalog is at AWSSymbols.md.

Service Imports

Import only the services used in each diagram. Each service has a <Category>/<ServiceName>.puml file that provides a macro of the same name.

AWS Service	Import Path	Macro
VPC	`AWSPuml/NetworkingContentDelivery/VirtualPrivateCloud.puml`	`VirtualPrivateCloud(alias, label, tech, desc)`
Subnet	`AWSPuml/NetworkingContentDelivery/VirtualPrivateCloudSubnet.puml`	`VirtualPrivateCloudSubnet(alias, label, tech, desc)`
NAT Gateway	`AWSPuml/NetworkingContentDelivery/VPCNATGateway.puml`	`VPCNATGateway(alias, label, tech, desc)`
Internet Gateway	`AWSPuml/NetworkingContentDelivery/VPCInternetGateway.puml`	`VPCInternetGateway(alias, label, tech, desc)`
S3	`AWSPuml/Storage/SimpleStorageService.puml`	`SimpleStorageService(alias, label, tech, desc)`
CloudFront	`AWSPuml/NetworkingContentDelivery/CloudFront.puml`	`CloudFront(alias, label, tech, desc)`
Route 53	`AWSPuml/NetworkingContentDelivery/Route53.puml`	`Route53(alias, label, tech, desc)`
EKS	`AWSPuml/Containers/ElasticKubernetesService.puml`	`ElasticKubernetesService(alias, label, tech, desc)`
RDS / Aurora	`AWSPuml/Database/Aurora.puml`	`Aurora(alias, label, tech, desc)`
API Gateway	`AWSPuml/ApplicationIntegration/APIGateway.puml`	`APIGateway(alias, label, tech, desc)`
Cognito	`AWSPuml/SecurityIdentityCompliance/Cognito.puml`	`Cognito(alias, label, tech, desc)`
IAM	`AWSPuml/SecurityIdentityCompliance/IdentityandAccessManagement.puml`	`IdentityandAccessManagement(alias, label, tech, desc)`
Secrets Manager	`AWSPuml/SecurityIdentityCompliance/SecretsManager.puml`	`SecretsManager(alias, label, tech, desc)`
ACM	`AWSPuml/SecurityIdentityCompliance/CertificateManager.puml`	`CertificateManager(alias, label, tech, desc)`
NLB	`AWSPuml/NetworkingContentDelivery/ElasticLoadBalancingNetworkLoadBalancer.puml`	`ElasticLoadBalancingNetworkLoadBalancer(alias, label, tech, desc)`
CloudWatch	`AWSPuml/ManagementGovernance/CloudWatch.puml`	`CloudWatch(alias, label, tech, desc)`
CloudFormation	`AWSPuml/ManagementGovernance/CloudFormation.puml`	`CloudFormation(alias, label, tech, desc)`
Amplify	`AWSPuml/FrontEndWebMobile/Amplify.puml`	`Amplify(alias, label, tech, desc)`
VPC Endpoint	`AWSPuml/NetworkingContentDelivery/VPCEndpoints.puml`	`VPCEndpoints(alias, label, tech, desc)`

Grouping and Boundaries

AWS architecture diagrams use nested containers to represent containment hierarchies. The library provides dedicated group macros that apply the correct AWS color palette automatically. Prefer these over plain rectangle when available.

Group Macros

The library provides group macros in AWSCommon.puml. These render with the official AWS color palette:

Macro	Purpose	Include
`AWSCloudGroup(alias, label)`	AWS Cloud boundary	`AWSCommon.puml`
`AWSAccountGroup(alias, label)`	AWS Account boundary	`AWSCommon.puml`
`RegionGroup(alias, label)`	AWS Region	`AWSCommon.puml`
`VPCGroup(alias, label)`	VPC boundary	`AWSCommon.puml`
`AvailabilityZoneGroup(alias, label)`	Availability Zone	`AWSCommon.puml`
`PrivateSubnetGroup(alias, label)`	Private subnet	`AWSCommon.puml`
`PublicSubnetGroup(alias, label)`	Public subnet	`AWSCommon.puml`
`GenericGroup(alias, label)`	Generic logical grouping	`AWSCommon.puml`

When group macros do not render correctly (e.g., in some PlantUML server versions), fall back to rectangle with explicit color conventions.

Hierarchy Levels

Use the following nesting order (outermost to innermost):

AWS Cloud — AWSCloudGroup(cloud, "AWS Cloud")
AWS Account — AWSAccountGroup(acct, "Account 009765408297")
Region — RegionGroup(region, "us-east-1")
VPC — VPCGroup(vpc, "VPC 10.0.0.0/16")
Availability Zone — AvailabilityZoneGroup(az, "AZ-a")
Subnet — PrivateSubnetGroup(priv, "Private Subnet") or PublicSubnetGroup(pub, "Public Subnet")

Fallback Color Conventions

When using plain rectangle instead of group macros:

Boundary	Background Color	Border
AWS Account	`WhiteSmoke` (light gray)	`DarkSlateGray` (AWS dark)
Region	`AliceBlue` (light blue)	`SteelBlue` (AWS blue)
VPC	`Honeydew` (light green)	`DarkGreen` (green)
Public Subnet	`MintCream` (green tint)	`ForestGreen`
Private Subnet	`LightCyan` (blue tint)	`MidnightBlue`
Security boundary	`LemonChiffon` (yellow tint)	`DarkGoldenrod`

Example: VPC with Subnets (Group Macros)

PlantUML diagram

Example: VPC with Subnets (Fallback Rectangle)

PlantUML diagram

Diagram Types

1. Runtime Resource Diagram

Shows the deployed AWS resources and their relationships at runtime. Focus on what exists in the AWS account after deployment.

Rules:

Use AWS service icons (macros) for individual resources.
Use rectangles with background colors for containment (VPC, subnets, AZs).
Show data flow arrows between resources (solid for primary, dashed for secondary/async).
Label arrows with the protocol or API (HTTPS, SigV4, OAC).
Include IAM roles only when they are central to the design (e.g., presigning roles, service account roles). Omit standard service-linked roles.
Include security boundaries (e.g., “CloudFront signed cookies”, “OAC”) as notes or annotations, not as separate resources.
Omit CloudFormation, CDK, and deployment machinery — those belong in deployment diagrams.

What to show:

Network topology (VPC, subnets, endpoints, gateways)
Compute (EKS, Lambda)
Storage (S3 buckets, databases)
Edge/CDN (CloudFront, Route53)
Security (IAM roles central to the design, Cognito, Secrets Manager)
Integration (API Gateway, NLB)

What to omit:

CloudFormation stacks
CDK constructs
CI/CD pipelines
Deployment scripts
CloudWatch (unless monitoring is the diagram’s topic)

2. Deployment Artifact Diagram

Shows the CDK constructs, CloudFormation stacks, and scripts that produce the runtime resources. Use UML class or object diagrams (not AWS icons) for these.

Rules:

Use class diagram notation for CDK constructs and stacks.
Show the construct tree: stacks contain constructs, constructs create resources.
Use stereotypes: <<Stack>>, <<Construct>>, <<CfnTemplate>>, <<Script>>.
Show dependencies with dashed arrows (..>): “Stack A depends on Stack B’s exports”.
Show composition with solid diamonds (*--): “Stack contains Construct”.
Include cross-stack exports as interface labels or notes.

Layout Guidelines

Left-to-right for data flow: Users/browsers on the left, backend services in the middle, storage on the right.
Top-to-bottom for containment: Account at the top, region, VPC, subnets, resources at the bottom.
Separate infrastructure-level from partition-level when both are shown: use distinct rectangles or a together block.
One diagram per concern: Do not mix runtime resources with deployment artifacts in the same diagram.
Keep diagrams focused: If a diagram exceeds ~25 resources, split it into multiple diagrams by concern area (networking, storage, compute, security).

Labeling

Resource labels: Use the logical name, not the CDK construct ID. E.g., “Image Asset Bucket” not “ImageAssetBucket”.
Arrow labels: Protocol or API operation. E.g., “HTTPS”, “SigV4 presigned POST”, “OAC (SigV4)”.
Boundary labels: Include the key identifier. E.g., “VPC 10.0.0.0/16”, “us-east-1”.
Notes: Use note right of or note over for security policies, IAM conditions, or configuration details that cannot be expressed as labels.

Validation

All AWS resource diagrams must be validated via the PlantUML MCP tool (generate_plantuml_diagram) before finalizing. Render to SVG in a scratch/ subdirectory. Verify that:

All icons render (no broken image placeholders).
Grouping boundaries are visually distinct.
Arrow labels are legible and do not overlap.
The diagram communicates the intended architecture at a glance.

Sources

AWS Official Resources

AWS Architecture Icons — official icon set, usage guidelines, and color palette. Defines the standard visual vocabulary for AWS architecture diagrams. Includes guidance on grouping (accounts, regions, VPCs, AZs), icon sizing, and when to use service icons vs. resource icons.
AWS Architecture Center — reference architectures and diagram examples showing AWS-recommended diagramming patterns for common workloads (web applications, serverless, container-based).
AWS Well-Architected Framework — architecture best practices across six pillars (Operational Excellence, Security, Reliability, Performance Efficiency, Cost Optimization, Sustainability). Informs what to emphasize in diagrams.
AWS Prescriptive Guidance — Architecture diagrams — AWS guide on creating effective architecture diagrams, including audience considerations, abstraction levels, and recommended tooling.

PlantUML and Tooling

awslabs/aws-icons-for-plantuml — PlantUML integration of the official AWS icons. Version v20.0 pinned for this project (Release 20, February 2025). The repository README documents all available macros, group functions, and theme options.
AWSSymbols.md — complete catalog of all available service symbols, their import paths, and macro signatures.
PlantUML Reference Manual — syntax reference for all diagram types (class, sequence, deployment, component).
PlantUML Standard Library — bundled icon libraries including AWS, Azure, GCP, and C4 model.
The Hitchhiker’s Guide to PlantUML — AWS — practical guide to creating AWS diagrams with PlantUML, including grouping patterns and layout techniques.
Documentation as Code for Cloud — PlantUML — patterns for embedding cloud architecture diagrams in documentation workflows.

Arda Workspace Conventions

PlantUML Guide — Arda-specific PlantUML conventions: embedding syntax, sequence diagram style, class diagram style, C4 model usage, validation requirements.
Authoring Guide — general document formatting, front matter, and link conventions.

AWS Service Documentation (Referenced in Diagrams)

The following service documentation pages were consulted for accurate representation of resource relationships and data flows: