Mermaid aws diagrams without fake service icons

The pictures people mean by mermaid aws diagrams are sketches of an Amazon account drawn with Mermaid's architecture-beta keyword, or with a flowchart when you care about the request path. The limitation comes first, because it changes every picture you draw. Mermaid architecture-beta does not ship official AWS service icons. There is no Lambda glyph, no S3 bucket mark, and no RDS logo in this diagram type. You get a small set of generic icons, and the service name has to live in the label.

I went looking for the Lambda icon anyway. I tried names that felt plausible. The box came back blank or generic, and the diagram looked like it knew something it didn't. A server icon labeled API is less impressive and more honest. I'd rather a reviewer ask "is this Lambda or a container?" than believe a glyph I invented.

What you are allowed to put on a box

architecture-beta draws groups, services, and edges. A group is a boundary. A service is a box with an icon and a label. An edge is a claim that something moves from one box to another.

The icons that are safe to use here are cloud, database, disk, internet, and server. That's the list I stick to. An unknown icon name is how you get a blank mark that readers interpret as "this one is special." It isn't special. It's missing.

The label is where the AWS name goes. service api(server)[API] is a server icon with the word API. service rds(database)[RDS] is a database icon with the word RDS. The icon says "this is a data store" or "this is a compute box." The label says which service you mean. If you need the reader to know it's Lambda, write that in the paragraph under the figure. Don't hunt for a Lambda shape. It isn't in the set, and drawing a lookalike is worse than a plain box because it pretends to be official.

The architecture diagram page is the syntax reference for groups, the in keyword, and edge sides. This page is the AWS-shaped warning on top of that syntax. The software architecture guide is about which picture to draw first, before you pick a keyword. Read that if you're still deciding between a context diagram and a deployment sketch. Stay here if you've already decided the audience wants the account boundary.

A small VPC, with the icons you actually have

This is the sketch I want in a design doc: one VPC, an API, a database, a disk for object storage, and the client outside the group. The client uses the internet icon because it's outside the account, not because the icon is an AWS service.

architecture-beta
    group vpc(cloud)[VPC]
    service api(server)[API] in vpc
    service rds(database)[RDS] in vpc
    service bucket(disk)[S3] in vpc
    service client(internet)[Client]
    client:R --> L:api
    api:R --> L:rds
    api:B --> T:bucket

The group id is vpc. The icon on the group is cloud, and the label is VPC. Both services that say in vpc sit inside that boundary. The client does not say in vpc, so it stays outside. That in clause is the membership. If you forget it, the API renders outside the VPC and the picture denies the network story you thought you drew. I forget it most often on the second service, the one I added later and didn't scroll up to check.

rds uses the database icon. The label says RDS. Nobody should read the icon as the RDS product mark. It's a generic database. bucket uses the disk icon. The label says S3. The disk is not the S3 logo. If that distinction matters to the audience, the paragraph under the figure has to say it in one sentence. I put that sentence in every doc that leaves the team, because a screenshot of this diagram will get pasted into a slide where the paragraph doesn't follow.

The edges say the client reaches the API, and the API reaches RDS and S3. They don't say which API call, which port, which subnet, or which IAM role. Those facts don't fit on an architecture-beta edge without turning the edge into a paragraph. Put them in a list under the figure, or draw the request path as a flowchart. An edge labeled with a full policy is how this diagram type becomes unreadable. api:R --> L:rds means the arrow leaves the right side of the API and arrives at the left side of RDS. T, B, L, and R are the four sides. If the arrow crosses the group in a way that looks backwards, swap the sides. Don't add a second arrow to "clarify" a layout problem. Two arrows are two claims.

I did not draw Lambda. If the API runs on Lambda, the label can stay API, and the prose can say "the API is a Lambda function." A box labeled Lambda with a server icon is acceptable only if you tell the reader the icon is generic. I still prefer API. The word Lambda on a non-Lambda glyph is how a later edit gets misread as a picture of the console.

The request path wants a flowchart

The architecture sketch answers "what sits inside the VPC, and what talks to what." It is a bad picture of a decision. Signed-in versus rejected is a branch. Branches are a flowchart. I keep both in the same doc, and I don't try to make the architecture diagram grow diamonds. It doesn't have diamonds.

flowchart TD
  client[Client] --> api[API]
  api --> auth{Signed in?}
  auth -->|No| reject[Reject]
  auth -->|Yes| read[Read RDS]
  read --> reply[Reply]

The client hits the API. The API checks the call. A missing session rejects. A valid session reads RDS and replies. S3 isn't on this chart because this request doesn't touch it. That's a feature. The architecture diagram showed S3 because S3 exists in the account. The flowchart shows S3 only if this path uses it. Mixing those questions is how you get a diagram where every request appears to write an object.

The cylinder you might be tempted to use, rds[(RDS)], is Mermaid's generic database shape. It is still not an AWS icon. I used a plain rectangle here so nobody treats the flowchart as a second attempt at the official icon set. The label carries the service name. Same rule as the architecture diagram, fewer decorations.

auth is a diamond because the path forks. reject does not continue into read. If your API logs the rejection to the database, draw that arrow and accept the extra line. Don't leave it out to keep the happy path clean. I shipped a version of this chart without the reject node, and the on-call doc made it look like every call read RDS. The 401s were in the logs the whole time. The chart was the thing that lied.

A flowchart is also the right place for retries, timeouts, and "fall back to the cache." Those are control flow. They are not icons. If you find yourself wanting a Lambda glyph so you can show a retry, you don't want the glyph. You want another box in this flowchart labeled with the behavior. The block diagram examples and a block diagram generator are a different beta syntax for boxes and groups. They are not a secret source of AWS logos either. Don't switch diagram types hoping the icons appear.

Labels do the work the icons can't

Write the service name a teammate would say out loud. API, RDS, S3, Client. Avoid internal pet names on the box and the real service name in a footnote. The screenshot will lose the footnote. I've seen a box called "store" that was RDS in one environment and a containerized Postgres in another. The label "store" made the migration look like a no-op. Label it RDS when it's RDS. When it stops being RDS, change the label in the same pull request as the infrastructure change.

Don't encode the account id, the region, and the ARN into the label. The box becomes a paragraph and the boundary disappears. Region belongs in the group label if the group is a region, or in the sentence under the figure if you only have one. group vpc(cloud)[VPC] is enough for a single-account sketch. If you have two VPCs, use two groups and name them so a person can tell them apart: the environment, or the name your Terraform module already uses. "Backend" is not a VPC name. I used "Backend" for a year and it slowly absorbed the CI runners, which were not in the VPC. The group became a feeling.

IAM is the thing people try to draw next, and it's the thing that blows up the sketch. An arrow is not a policy. If the API's task role can read one bucket prefix, write that as a sentence. An edge from API to S3 already says the path exists. A second edge labeled s3:GetObject is usually noise unless the review is specifically about that call. For a permissions review, a table under the figure beats a diagram. I tried the diagram. The arrow labels wrapped, the sides got shuffled, and we still had to read the policy JSON.

Queues and functions can be server icons with honest labels if you truly need them on the sketch. A server icon labeled Worker is fine. A server icon you hope reads as Lambda is the trap. Say worker, or say the role it plays. There is no official icon coming to save the ambiguity.

Edges that overclaim

Every edge is a sentence. "The API reads and writes RDS" might be two permissions and one network path. One arrow doesn't distinguish read from write. If the difference matters, the flowchart or the prose has to say it. Don't add arrowheads in both directions unless both directions are real. A reply is not a second architecture. The request path flowchart already has a reply node.

An edge from the client straight to RDS is a serious claim. It says the database is reachable from the client, which for this sketch it should not be. I added that edge once because the generator connected every box to every other box. It looked complete. It described a security bug we didn't have. Delete edges that describe paths you would page someone for. The diagram is not a mesh of "could theoretically."

The client sitting outside the group is the other claim. If the client is a bastion inside the VPC, put it inside with in vpc and don't use the internet icon for a machine you operate. The internet icon is for something on the other side of the boundary. I use it for a browser or a partner webhook. I don't use it for our own NAT gateway. A NAT gateway is a design detail this sketch isn't trying to hold. If the review is about the NAT gateway, this is the wrong diagram. Draw the subnet layout in the tool your cloud team already trusts, and keep Mermaid for the one-page version.

A schematic diagram is sometimes what people actually wanted: boxes and lines, not an account boundary. Text to a schematic is the same impulse from a sentence. Use those when you don't have a VPC to claim. Using architecture-beta for a schematic, then calling the group "AWS" because the icon is a cloud, is how a generic drawing gets mistaken for an infrastructure review. The group label should be a boundary you can point at in the console. VPC is a boundary. "Cloud" is a mood.

When the sketch should stop growing

Three services and a client is about as much as I want on one architecture-beta figure. The fourth box is usually a queue, and the fifth is "while we're here, the cache." Each one is defensible. Together they turn the boundary into a parking lot. Split by request path. The flowchart can mention the cache for the read path. The architecture diagram can mention the cache only if the audience needs to see that it lives in the VPC.

If the thing you're drawing is a cluster rather than an account, start from a template instead of stretching this VPC forever. The Kubernetes deployment template is a denser layout for that boundary. The microservices template is the one I open when the question is several services and the calls between them, not subnets. Both will still obey the same icon limits if they use architecture-beta. Don't "fix" a template by pasting AWS logo names into the icon slot. You'll get blank marks and a false sense that the page now documents the console.

Generated diagrams need the same pass. Describe "a VPC with an API and RDS" and then delete any icon that isn't cloud, database, disk, internet, or server. Rename any label that says a cute name instead of the service. Check every in clause against the boundary you meant. I don't trust a draft's edges. I trust them after I've read each one as a sentence and rejected the ones that would be incidents.

Multi-region is two groups, not one group with a slash in the label. If you can't say which services are in which region, you aren't ready to draw both. Draw the region you can explain. A wrong second region is a confident outage story waiting for an incident channel.

Draw the boundary, then draw the path

Keep the architecture-beta figure and the flowchart in the same Markdown file. The first answers where the boxes live. The second answers what a single call does. Update them in the same pull request when the path changes. A new edge to S3 on the architecture diagram, with no change to the flowchart, means you added a service to the account and not to this request, or you forgot the flowchart. Say which.

Open the editor to move the sides of an edge until the arrow doesn't cross the group backwards. Paste the source back into the doc. Don't replace the source with a PNG of the console. The console has the official icons, and it's the right tool for a console conversation. It is a bad git diff. The Mermaid file is the diff. The missing Lambda glyph is the reminder that this file was never trying to be the console.