Skip to main content

​
AWS Architecture Diagrams — Complete Reference

Load this file when the user requests cloud architecture diagrams, AWS infrastructure visualization, or architecture-beta diagrams.

​
Overview

Mermaid’s architecture-beta diagram type enables cloud architecture visualization with icons representing services. Combined with Iconify icon packs, it produces professional infrastructure diagrams with real AWS service icons. CRITICAL LIMITATION — The “Arrow Distance” Bug: Because architecture-beta is built on a rigid grid system without edge routing algorithms, diagrams with more than 6-8 nodes or complex crossing relationships will suffer from massive, unreadable distances between nodes and arrows crossing over boxes. The Golden Rule for AWS Diagrams:
  • Simple (< 8 nodes, linear flow): Use architecture-beta with --icons logos.
  • Complex (> 8 nodes, microservices, multiple tiers): You MUST use Option A: C4 Container Diagram. C4 uses the dagre layout engine which perfectly spaces nodes and routes arrows beautifully.
Important — Icon Rendering:
  • architecture-beta requires Mermaid v11+
  • Icons from Iconify packs (logos:aws-*) require icon pack registration at render time — they do NOT work in static markdown renderers (GitHub, GitLab)
  • When rendering with the render script, use --icons logos to auto-register icon packs
  • For environments without icon pack support, the built-in icons (cloud, database, disk, server, internet) work everywhere as a fallback
  • For universal compatibility, consider using C4 diagrams with descriptive labels as an alternative

​
Basic Syntax

​
Building Blocks

ElementSyntaxPurpose
Groupgroup id(icon)[Label]Visual boundary (VPC, region, account)
Serviceservice id(icon)[Label]Individual service node
Service in groupservice id(icon)[Label] in groupIdService inside a group
EdgeserviceA:Side --> Side:serviceBConnection with direction

​
Edge Sides

Edges connect from/to specific sides of services:
  • L — Left
  • R — Right
  • T — Top
  • B — Bottom
api:R --> L:lambda        %% api's right connects to lambda's left
lambda:B --> T:db          %% lambda's bottom connects to db's top

​
Edge Types

serviceA:R --> L:serviceB     %% Solid arrow (default)
serviceA:R -- L:serviceB      %% Solid line (no arrow)

​
Icon Options

​
Option 1: Iconify Icons (Best Visual Quality)

Mermaid supports 200,000+ icons from iconify.design via registerIconPacks(). The logos pack provides the best AWS icons. To render with these icons, use --icons logos with the render script. Format: logos:aws-{service-name}

​
Option 2: Built-in Icons (Universal Compatibility)

Available everywhere without any registration. Use these when targeting markdown renderers or when icon packs aren’t available: cloud, database, disk, internet, server

​
AWS Service Icons Catalog (Iconify logos Pack)

​
Compute

ServiceIcon name (logos)Built-in fallback
Lambdalogos:aws-lambdaserver
EC2logos:aws-ec2server
ECSlogos:aws-ecsserver
Fargatelogos:aws-fargateserver
Elastic BKlogos:aws-elastic-beanstalkserver

​
Storage

ServiceIcon name (logos)Built-in fallback
S3logos:aws-s3disk
EBSlogos:aws-ebsdisk
EFSlogos:aws-efsdisk
Glacierlogos:aws-glacierdisk

​
Database

ServiceIcon name (logos)Built-in fallback
RDSlogos:aws-rdsdatabase
DynamoDBlogos:aws-dynamodbdatabase
ElastiCachelogos:aws-elasticachedatabase
Auroralogos:aws-auroradatabase
Redshiftlogos:aws-redshiftdatabase
DocumentDBlogos:aws-documentdbdatabase

​
Networking

ServiceIcon name (logos)Built-in fallback
API Gatewaylogos:aws-api-gatewayserver
CloudFrontlogos:aws-cloudfrontinternet
Route 53logos:aws-route53internet
ELB/ALBlogos:aws-elastic-load-balancingserver
VPClogos:aws-vpccloud

​
Messaging

ServiceIcon name (logos)Built-in fallback
SQSlogos:aws-sqsserver
SNSlogos:aws-snsserver
EventBridgelogos:aws-eventbridgeserver
Kinesislogos:aws-kinesisserver

​
Integration & Orchestration

ServiceIcon name (logos)Built-in fallback
Step Functionslogos:aws-step-functionsserver
AppSynclogos:aws-app-syncserver

​
Monitoring & Security

ServiceIcon name (logos)Built-in fallback
CloudWatchlogos:aws-cloudwatchserver
IAMlogos:aws-iamserver
Cognitologos:aws-cognitoserver
WAFlogos:aws-wafserver

​
DevOps & CI/CD

ServiceIcon name (logos)Built-in fallback
CodePipelinelogos:aws-codepipelineserver
CodeBuildlogos:aws-codebuildserver
CodeDeploylogos:aws-codedeployserver
ECRlogos:aws-ecrserver

​
ML/AI

ServiceIcon name (logos)Built-in fallback
SageMakerlogos:aws-sagemakerserver
Note: Not all AWS services have icons in the logos pack. If a specific icon is not available, use the closest category-appropriate built-in icon as fallback. You can verify icon availability at https://icon-sets.iconify.design/?q=aws.

​
Architecture Patterns

​
Pattern 1: Three-Tier Web Application

With Iconify Icons (best quality — requires --icons logos): With Built-in Icons (universal compatibility):

​
Pattern 2: Serverless API

​
Pattern 3: Data Pipeline

​
Pattern 4: CI/CD Pipeline

​
Rendering with Icon Packs

​
Using the Render Script

To render architecture-beta diagrams with proper AWS icons: 
node $SKILL_DIR/scripts/render.mjs \
  --input diagram.mmd \
  --output diagram.svg \
  --format svg \
  --icons logos
The --icons logos flag tells the render script to register the Iconify logos pack which includes all logos:aws-* icons. The render script uses a Puppeteer-based pipeline for icon-enabled rendering.

​
Multiple Icon Packs

You can register multiple packs: 
node $SKILL_DIR/scripts/render.mjs \
  --input diagram.mmd \
  --output diagram.svg \
  --icons logos,fa
Available packs: logos (AWS + tech logos), fa (Font Awesome icons).

​
How Icon Registration Works

The render script generates an HTML page with Mermaid loaded, registers icon packs via mermaid.registerIconPacks(), renders the diagram, and captures the SVG output. This is equivalent to: 
import mermaid from 'mermaid'

mermaid.registerIconPacks([
  {
    name: 'logos',
    loader: () => fetch('https://unpkg.com/@iconify-json/logos/icons.json').then((res) => res.json()),
  },
])

​
Fallback Strategy

When architecture-beta is not supported by the rendering environment OR icons don’t render, use these alternatives:

​
Option A: C4 Container Diagram (Best Alternative)

C4 diagrams work everywhere and convey the same information:

​
Option B: Flowchart with AWS Labels and Professional Styling

​
Best Practices

  1. Group by boundary — VPC, subnet, region, account
  2. Left-to-right flow — request path should read naturally
  3. Limit to 12 services max — split complex architectures into multiple focused diagrams
  4. Show only one concern per diagram — networking, compute, data, separately
  5. Include external systems — show what connects from outside
  6. Security boundaries — show public vs private subnets
  7. Use Iconify icons when rendering — logos:aws-* for best visual quality
  8. Use built-in icons for docs — cloud, database, disk, server, internet for markdown compatibility
  9. Always provide both versions — one with Iconify icons for rendered output, one with built-in for inline markdown