How do you get ChatGPT or Claude to generate valid Mermaid AWS architecture diagrams?

Why do LLMs invent Mermaid AWS icon slugs that do not exist?

Large language models predict the next token from a distribution over plausible continuations. When you ask for an AWS service slug, the model's training data contains thousands of references to aws:lambda, aws:s3, and aws:ec2 — because that is how people informally talk about AWS in blog posts, GitHub issues, and Stack Overflow threads. The actual Mermaid slugs are far less frequent in the corpus, so the model averages toward the plausible-but-wrong form.

There are also two equally valid prefixes — arch- (architectural product icons) and res- (resource icons) — and the choice depends on what the icon is being used for. A model that has not been explicitly grounded does not know which prefix to pick, so it omits both and produces aws:lambda instead of aws:arch-aws-lambda.

This is the same class of failure as confidently inventing function names that do not exist in a library. The model is not lying. It is filling in the most probable token, and the most probable token is wrong.

What does a typical Mermaid AWS hallucination look like?

Here is the ungrounded output from a single prompt — what every frontier model produces if you ask for a Mermaid architecture-beta diagram of a VPC with an EC2 instance, a Lambda, and an S3 bucket. The structure is fine. Every slug name is wrong.

architecture-beta
    group vpc(aws:vpc)[VPC]
        service ec2(aws:ec2)[EC2] in vpc
        service lambda(aws:lambda)[Lambda] in vpc
    service s3(aws:s3)[S3 Bucket]
    ec2:R <--> L:lambda
    lambda:R <--> L:s3

Four out of four service icons fail to render. Here is what the same diagram looks like when the model has been grounded with the LatixEngine icon catalog — same structure, real slugs, renders cleanly.

architecture-beta
    group vpc(aws:virtual-private-cloud-vpc)[VPC]
        service ec2(aws:ec2-instance-contents)[EC2] in vpc
        service lambda(aws:arch-aws-lambda)[Lambda] in vpc
    service s3(aws:arch-amazon-simple-storage-service)[S3 Bucket]
    ec2:R <--> L:lambda
    lambda:R <--> L:s3

Which AWS slugs do LLMs get wrong most often?

These are the slugs the model will reach for if you do not ground it. Always rewrite from the right column. The authoritative list is at latixengine.com/icons.json.

How do you ground a model with the LatixEngine icon catalog?

There are three grounding strategies, ranked by accuracy. Pick the one that fits your tooling.

• Inline paste — fetch latixengine.com/icons.json and paste the JSON (or a filtered AWS-only subset) directly into the prompt. Works in any chat UI. Costs context tokens but produces near-perfect slugs in a single shot.
• Tool call — give the model a search function over the catalog (Claude Code, Cursor agents, OpenAI function calling). The model looks up each service as it builds the diagram. Lower token cost, slightly more latency.
• Retrieval — index the catalog in a vector store and let the model retrieve the relevant entries per query. Overkill for a 1698-row catalog, but useful if you are generating dozens of diagrams in a batch.

What is a prompt template that actually produces valid Mermaid AWS source?

This is the inline-paste template. Drop it into any chat UI, replace the goal at the bottom, and you will get correct slugs on the first response.

You are generating a Mermaid architecture-beta diagram.

You MUST use only icon slugs from the following catalog. Do not invent
slugs. If you cannot find an appropriate icon, fall back to a generic
shape like internet, server, database, or cloud.

Catalog (provider:slug — human name):
- aws:arch-aws-lambda — AWS Lambda
- aws:arch-amazon-simple-storage-service — S3
- aws:arch-amazon-api-gateway — API Gateway
- aws:ec2-instance-contents — EC2 instance
- aws:virtual-private-cloud-vpc — VPC (use as a group)
- aws:public-subnet — Public subnet (use as a group)
- aws:private-subnet — Private subnet (use as a group)
- aws:res-amazon-vpc-internet-gateway — Internet Gateway
- aws:res-amazon-vpc-nat-gateway — NAT Gateway
- aws:region — AWS Region (use as a group)
- (paste the rest from latixengine.com/icons.json)

Syntax rules:
- Diagram starts with: architecture-beta
- Service declaration: service <id>(<slug>)[<label>]
- Group declaration: group <id>(<slug>)[<label>]
- "service x() in y" places x inside group y
- Edges use port-anchored syntax: source:R <--> L:target
  where ports are L, R, T, B

Goal: <describe the AWS architecture you want here>

For an even tighter prompt, filter the catalog down to just the services you care about — a 50-line list of relevant slugs is more reliable than the full 856-row AWS catalog because the model has less to scan.

How do you validate AI-generated Mermaid diagrams before publishing?

Even with a grounded prompt, expect one or two slug errors per diagram. The fastest validation loop is to paste the output into the LatixEngine editor, where missing icons render as a clear error and you can fix them in place against the icon picker.

For batch generation (CI pipelines, automated docs), a simpler check is to grep the generated Mermaid source for the regex (aws|azure|gcp):[a-z0-9-]+, diff the captured slugs against the keys in icons.json, and fail the build on any mismatch. That is the same one-liner LatixEngine uses to validate its own documentation against the catalog before release.

Which workflow gives the best results — chat, IDE agents, or terminal tools?

All three work, but the failure modes differ. This table compares the realistic accuracy you can expect for a 10-node AWS architecture across the major LLM-driven workflows, with and without grounding.

The pattern: ungrounded chat will fail no matter how powerful the model is. Grounding fixes the problem cheaply. The choice between inline paste, tool call, and retrieval comes down to how much context you want to spend and how many diagrams you are generating.

Does the same approach work for Azure and GCP diagrams?

Yes — the failure mode is identical. LLMs hallucinate azure:cosmos-db (real: azure:service-azure-cosmos-db) and gcp:region (real: gcp:project). Filter icons.json by provider and inline-paste the relevant slice into the prompt, and the same grounding pattern works for all three clouds.

If you want the by-hand syntax tutorial without any LLM involved, see our guide on how to draw AWS architecture diagrams in Mermaid.