Cloud architecture
Cloud architecture
How to draw an AWS, Azure, or Google Cloud architecture that reads like a cloud architecture: typed groups for accounts, regions, and networks, a product icon on every service, and technology marks where they help. It is written for an AI agent first, so each step names the tool to call and says what a warning means. A person can follow the same steps by hand. This page holds the recipe; the pages in the Cloud architecture section hold the details, each with pictures drawn by the same renderer a diagram uses.
TL;DR
| Question | Answer |
|---|---|
| What do I write first? | flow "Title" provider=azure direction=down. The provider on the header sets the icons of every group. |
| How do I draw a region, a network, or a subnet? | A group with type=region, type=network, or type=subnet. The type picks the icon, the tone, and a solid, dashed, or dotted frame. See Group types for all 30, each drawn. |
| How do I draw a service? | One node per service, with icon=<provider>:<product>, for example icon=azure:cosmos-db. |
| How do I find the icon? | Call map_icons with every product name from the request, or search_icons for one name, and use the first result. Never invent a name. See Icon names and lookup. |
| Where do I see an icon before I use it? | On the icon pages: AWS, Azure, Google Cloud, other providers, and generic and technology icons. Each icon is drawn above its name. |
| How do I mark a technology? | stack=simple:angular,simple:typescript on the node, up to three marks. See Marks, second lines, and overlays. |
| How do I show an event or a webhook? | a ..> b : "event", a dotted line with an arrowhead. Every line style is drawn on Frames, tones, lines, and symbols. |
| How do I show a scaling group across two zones? | An overlay line after the nodes: overlay set "Web machines" type=scale-group members=w1,w2. |
| Is there a starting point? | Yes. find_pattern returns checked, ready-made diagrams, such as a three-tier network or a two-zone network. See the architecture patterns guide and the examples. |
| What if I miss something? | draw_diagram and validate_diagram return warnings with the exact fix: W204 for a node icon, W205 for a group type. |
| How big can it be? | About 15 nodes, and one more for each group, up to 25. Split a larger system by plane: network, data, delivery. |
1. The five-step recipe
Follow these steps in order. Each one ends with a check. If the request matches a common architecture, such as a three-tier network or a serverless API, call find_pattern first and adapt the pattern it returns: the groups, icons, and warnings are already right, and steps 2 to 5 become a check of the renamed result. See the architecture patterns guide.
- Pick the provider. Put
provider=aws,provider=azure, orprovider=gcpon the header. For a multi-cloud diagram, leave it off the header and putprovider=on the top group of each cloud; nested groups inherit it. - Build the group tree from the top down. Write the outermost container first, then what it holds, giving every group a
type=. A typical AWS tree is account, region, network, subnets. Name each group the way the provider does:eu-west-1,Application VPC,Private subnets. The group types page lists the closed set of types. - Add one node per service. A service is a thing in the request: a load balancer, a database, a queue. One node for the service, not one per instance. Label the node with the product name next to its icon.
- Map every service to its icon. Call
map_iconsonce with the product names exactly as the request writes them, orsearch_iconsfor one name, take the first result, and write it asicon=. Then callvalidate_diagram(ordraw_diagram): an unknown name is an error with the nearest valid one. - Read the warnings.
validate_diagramreports a node whose label names a product but has no icon (W204), and a group whose name matches a type but has none (W205). Each gives the exact text to add. Add it, or writeicon=noneon a node that should stay plain, and validate again until no warning is left.
A session for the request "a function that resizes images stored in S3" looks like this:
| Call | Input | What comes back |
|---|---|---|
get_diagram_syntax | kind set to flow | Group types, node options, arrows, and a complete cloud architecture example |
map_icons | ["Lambda", "S3"] with provider set to aws | aws:lambda and aws:s3, each with a confidence |
search_icons | lambda | aws:lambda first. Use it for one name when map_icons is more than you need. |
validate_diagram | the source | valid: true, or errors with a line, a column, and a hint |
outline_diagram | the source | The diagram as text, to check against the request |
render_diagram | the source | The SVG |
draw_diagram | the source | The three calls above in one: warnings, outline, and the SVG in both themes |
2. Where each detail lives
Each page below does one job and shows every item it names drawn by the renderer, with the exact source beside the picture, so you can copy what you see.
| Page | What it holds | Read it when |
|---|---|---|
| Group types | The closed list of type= values, each drawn, and the icon each type draws for each provider | You choose a type for a group |
| Frames, tones, lines, and symbols | Frame styles, tones in light and dark, nesting depth, every edge style and arrowhead, labels, and the marks a node or group can carry | You want to know what a line or a color means |
| Icon names and lookup | How provider:product resolves, how search ranks, and how to map a product name to an icon | You have a product name and need the icon= |
| AWS icons, Azure icons, Google Cloud icons | Every icon of the set, grouped by category, drawn, with its exact name and aliases | You want to see the icon before you use it |
| Other provider icons | Alibaba Cloud, Oracle Cloud Infrastructure, IBM Cloud, Cloudflare, DigitalOcean, and Vercel | The request names one of those providers |
| Generic and technology icons | General icons, technology marks, status icons, and the glyph of each kind of service | You need a mark for a technology or a status |
| Marks, second lines, and overlays | stack= marks, event edges, sub=, and overlay | A service needs a technology mark or spans two zones |
| Examples | A web app on Azure, a two-zone network on AWS, and a serverless API on Google Cloud | You want a complete diagram to read |
3. Do and do not
| Do | Do not |
|---|---|
Call map_icons or search_icons for every product and use the first result | Invent an icon name; validate_diagram rejects it with the nearest valid one |
| Use the product name from the request as the label, next to its icon | Label a node with only an icon, or with only a generic word such as Database |
| Draw one node per service | Draw one node per instance, or one per subnet for the same service |
Give every group a type= and name it the way the provider does | Colour a group by hand, or use type=trust-boundary for a network |
| Put the account, region, and network groups around the services, from the outside in | List the services flat and write the region in a label |
Set provider= once on the header | Repeat provider= on every group of a single-cloud diagram |
Add the exact text a W204 or W205 warning gives, or write icon=none | Ignore a suggestion without deciding |
| Split a diagram that passes its node limit (15, plus one for each group, up to 25) by plane: network, data, delivery | Raise the node count by shrinking the text |
See also
| Doc | Why |
|---|---|
| Group types | The 30 types of group, each drawn |
| Icon names and lookup | From a product name to an icon= |
| Examples | Three complete cloud diagrams |
| Writing diagrams | The whole language, kind by kind |
| Architecture patterns | Ready-made, checked diagrams to start from, each with slots to rename |
| Writing diagrams with an agent | The validate-and-fix loop an agent follows |
| Language reference | Every group type, node type, arrow, option, and diagnostic code |
| Icon reference | Every bundled icon and how search ranks them |
| Tool reference | map_icons, search_icons, draw_diagram, and the other tools |