# Cloud architecture

> Page: https://docs.plotwork.dev/cloud-architecture. Index of every page: https://docs.plotwork.dev/llms.txt

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](https://docs.plotwork.dev/cloud-architecture/group-types.md) 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](https://docs.plotwork.dev/cloud-architecture/icon-names.md). |
| Where do I see an icon before I use it? | On the icon pages: [AWS](https://docs.plotwork.dev/cloud-icons/aws.md), [Azure](https://docs.plotwork.dev/cloud-icons/azure.md), [Google Cloud](https://docs.plotwork.dev/cloud-icons/google-cloud.md), [other providers](https://docs.plotwork.dev/cloud-icons/other-providers.md), and [generic and technology icons](https://docs.plotwork.dev/cloud-icons/generic.md). 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](https://docs.plotwork.dev/cloud-architecture/marks-and-overlays.md). |
| 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](https://docs.plotwork.dev/cloud-architecture/lines-and-symbols.md). |
| 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](https://docs.plotwork.dev/architecture-patterns.md) and the [examples](https://docs.plotwork.dev/cloud-architecture/examples.md). |
| 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](https://docs.plotwork.dev/architecture-patterns.md).

1. **Pick the provider.** Put `provider=aws`, `provider=azure`, or `provider=gcp` on the header. For a multi-cloud diagram, leave it off the header and put `provider=` on the top group of each cloud; nested groups inherit it.
2. **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](https://docs.plotwork.dev/cloud-architecture/group-types.md) page lists the closed set of types.
3. **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.
4. **Map every service to its icon.** Call `map_icons` once with the product names exactly as the request writes them, or `search_icons` for one name, take the first result, and write it as `icon=`. Then call `validate_diagram` (or `draw_diagram`): an unknown name is an error with the nearest valid one.
5. **Read the warnings.** `validate_diagram` reports 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 write `icon=none` on 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](https://docs.plotwork.dev/cloud-architecture/group-types.md) | 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](https://docs.plotwork.dev/cloud-architecture/lines-and-symbols.md) | 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](https://docs.plotwork.dev/cloud-architecture/icon-names.md) | 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](https://docs.plotwork.dev/cloud-icons/aws.md), [Azure icons](https://docs.plotwork.dev/cloud-icons/azure.md), [Google Cloud icons](https://docs.plotwork.dev/cloud-icons/google-cloud.md) | 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](https://docs.plotwork.dev/cloud-icons/other-providers.md) | Alibaba Cloud, Oracle Cloud Infrastructure, IBM Cloud, Cloudflare, DigitalOcean, and Vercel | The request names one of those providers |
| [Generic and technology icons](https://docs.plotwork.dev/cloud-icons/generic.md) | 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](https://docs.plotwork.dev/cloud-architecture/marks-and-overlays.md) | `stack=` marks, event edges, `sub=`, and `overlay` | A service needs a technology mark or spans two zones |
| [Examples](https://docs.plotwork.dev/cloud-architecture/examples.md) | 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](https://docs.plotwork.dev/cloud-architecture/group-types.md) | The 30 types of group, each drawn |
| [Icon names and lookup](https://docs.plotwork.dev/cloud-architecture/icon-names.md) | From a product name to an `icon=` |
| [Examples](https://docs.plotwork.dev/cloud-architecture/examples.md) | Three complete cloud diagrams |
| [Writing diagrams](https://docs.plotwork.dev/writing-diagrams.md) | The whole language, kind by kind |
| [Architecture patterns](https://docs.plotwork.dev/architecture-patterns.md) | Ready-made, checked diagrams to start from, each with slots to rename |
| [Writing diagrams with an agent](https://docs.plotwork.dev/mcp/agent-loop.md) | The validate-and-fix loop an agent follows |
| [Language reference](https://docs.plotwork.dev/reference/language.md) | Every group type, node type, arrow, option, and diagnostic code |
| [Icon reference](https://docs.plotwork.dev/reference/icons.md) | Every bundled icon and how search ranks them |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | `map_icons`, `search_icons`, `draw_diagram`, and the other tools |