How to draw an AWS architecture diagram with Mermaid

A step-by-step way to diagram an AWS system as code: list the components, group them by boundary, label the connections, then add official AWS icons and a clean layout.

Updated November 19, 2026 · 3 min read

Architecture diagrams go stale because they live in a slide or a drawing tool nobody opens. Writing them in Mermaid keeps them next to the code, in a format you can review in a pull request. This guide builds a serverless order system step by step, then makes it presentation-ready with official AWS icons.

1. List the components

Start with the pieces, not the boxes. For a typical serverless shop:

  • Customers using the web and mobile apps
  • CloudFront in front, for caching and TLS
  • Cognito for sign-in
  • API Gateway receiving requests
  • Lambda functions for orders and fulfilment
  • SQS between them, so a slow step doesn't block checkout
  • DynamoDB for orders, S3 for receipts

2. Connect them in plain Mermaid

Write the request path first, left to right, and label each connection with what travels on it. Labels are the part people read most.

flowchart LR
  users([Customers]) -->|HTTPS| cdn[CloudFront]
  users -.->|sign in| auth[Cognito]
  cdn --> api[API Gateway]
  api --> orders[Orders Lambda]
  orders --> table[(Orders table)]
  orders -->|OrderCreated| queue[Order queue]
  queue --> worker[Fulfilment Lambda]
  worker --> bucket[(Receipts bucket)]

That is already a useful diagram, and it is twelve lines of text.

3. Group by boundary

Put what runs inside your AWS account in a subgraph. Use subgraphs for whatever boundary matters to the reader: an account, a region, a VPC, or a team.

flowchart LR
  users([Customers]) -->|HTTPS| cdn[CloudFront]
  users -.->|sign in| auth[Cognito]
  subgraph region [AWS eu-west-1]
    api[API Gateway] --> orders[Orders Lambda]
    orders --> table[(Orders table)]
    orders -->|OrderCreated| queue[Order queue]
    queue --> worker[Fulfilment Lambda]
    worker --> bucket[(Receipts bucket)]
  end
  cdn --> api

4. Add official AWS icons

Icons make an architecture diagram readable at a glance. In Flowgraph Studio, a node label can start with an icon and carry a subtitle, badges and a status light:

API["@icon:aws:lambda **Orders API** | sub:Python 3.12 | badge:256MB:emerald | status:healthy"]

The same diagram with icons, drawn top to bottom so it fits a page:

flowchart TB
  USERS(["@icon:lucide:users **Customers** | sub:Web and mobile"])
  CDN["@icon:aws:cloudfront **CloudFront** | sub:CDN and TLS"]
  AUTH["@icon:aws:cognito **Cognito** | sub:Sign-in"]
  subgraph REGION["@icon:logos:aws **AWS** | sub:eu-west-1"]
    API["@icon:aws:api-gateway **API Gateway** | sub:REST API"]
    ORDERS["@icon:aws:lambda **Orders** | sub:Lambda | status:healthy"]
    QUEUE["@icon:aws:simple-queue-service **Order queue** | sub:SQS"]
    WORKER["@icon:aws:lambda **Fulfilment** | sub:Lambda"]
    TABLE[("@icon:aws:dynamodb **Orders table** | sub:DynamoDB")]
    BUCKET[("@icon:aws:simple-storage-service **Receipts** | sub:S3")]
  end
  USERS -->|HTTPS| CDN --> API
  USERS -.->|sign in| AUTH
  API --> ORDERS --> TABLE
  ORDERS -->|OrderCreated| QUEUE --> WORKER --> BUCKET

Icon names follow the pattern set:name. A few you will use often:

Service Icon
Lambda aws:lambda
API Gateway aws:api-gateway
DynamoDB aws:dynamodb
S3 aws:simple-storage-service
SQS aws:simple-queue-service
SNS aws:simple-notification-service
CloudFront aws:cloudfront
Cognito aws:cognito
RDS / Aurora aws:rds, aws:aurora
EventBridge aws:eventbridge
CloudWatch aws:cloudwatch

You don't need to remember them: the Rich node builder in the editor searches more than 15,000 icons by name or abbreviation, including Google Cloud, Azure and Kubernetes, and writes the line for you. To skip the blank page, the Templates page has ready-made AWS, Azure and Google Cloud architectures (serverless order processing, static websites, a three-tier app in a VPC, streaming analytics and more) to adapt.

5. Or use Mermaid's architecture diagram

Mermaid also has a dedicated architecture-beta diagram, with groups, services and edges that attach to a side of each box (L, R, T, B). Flowgraph Studio supports the same icon sets in it:

architecture-beta
  group cloud(logos:aws)[AWS]
  service api(aws:api-gateway)[API Gateway] in cloud
  service fn(aws:lambda)[Orders] in cloud
  service db(aws:dynamodb)[Orders table] in cloud
  api:R --> L:fn
  fn:R --> L:db

Flowcharts are more flexible (labels on links, shapes, styling); architecture diagrams give a tidier grid for simple service maps.

Tips for diagrams people actually read

  • One question per diagram. "How does an order flow?" and "What runs where?" are two diagrams. Past about 15 boxes, split it.
  • Left to right for requests, top to bottom for layers.
  • Label every connection with the protocol, event or data that moves.
  • Use dotted links for asynchronous or optional paths, solid for the main path.
  • Show state with color, not words: a status light or a badge says "degraded" faster than a note.
  • Match the destination: a dark theme suits a screen share; for a design doc or a slide, a light style such as Print Ready or Slide Deck reads better and prints cleanly.

Keep it up to date

Because the diagram is text, it can live in the repository next to the infrastructure code and change in the same pull request. With Flowgraph Studio's render API a build step can turn the .mmd file into an SVG or PNG with your theme, so the image in your docs always matches the code.

Want a refresher on the syntax? See the Mermaid flowchart cheat sheet.

More guides