Marks, second lines, and overlays
How to put technology marks on a service, a second line and marks on a group tab, an overlay around a set that spans zones, and a dotted line for an event. It is for anyone drawing a cloud architecture, human or AI agent. Frames, tones, and every line style are drawn on Frames, tones, lines, and symbols.
TL;DR
| Question | Answer |
|---|---|
| How do I mark a technology on a service? | stack=simple:angular,simple:typescript on the node, up to three marks. The card grows to hold them. |
| Which set do the marks come from? | Usually simple, the technology and brand logos. Find the name with search_icons. |
| What if the technology has no mark? | Write it in sub= as text. The simple set has a mark for .NET (simple:dotnet) but none for C#, so write a .NET service as simple:dotnet. |
| How do I show an event or a webhook? | A dotted arrow: registry ..> api : "webhook". |
| How do I add a second line to a group? | sub="10.0.1.0/24" on the group. |
| How do I put marks on a group? | stack=simple:dotnet on the group, written like the marks of a node. |
| How do I show a scaling group across two zones? | One overlay line after the nodes, listing its members. |
| What warns me about an overlay? | W206, when the frame would also surround a node that is not a member. |
1. Technology marks
stack= puts small marks on a card for the technologies a service is built with. It takes up to three icon references, usually from the simple set, and the card grows to hold them. A mark never covers the text or the icon.
node app storage "Web app" icon=azure:blob-storage stack=simple:angular,simple:typescriptnode api service "Orders API" icon=azure:app-service stack=simple:dotnetUse a mark for the technology of the code, not for the cloud product, which already has its icon.
flow "Marks on two services" desc="A web app with Angular and TypeScript marks calls an API with a .NET mark." direction=rightnode app storage "Web app" icon=azure:blob-storage stack=simple:angular,simple:typescriptnode api service "Orders API" icon=azure:app-service stack=simple:dotnetapp -> api : "HTTPS"Nodes:
- Web app, storage, stack: angular, typescript
- Orders API, service, stack: dotnet
Connections:
- Web app to Orders API: HTTPS
2. Event edges
A dotted arrow, ..>, is an asynchronous call: a webhook, an event, a pull, or a push that is not waited for. Use -> for a call that waits, and --> for a response or a looser dependency.
registry ..> api : "webhook, Docker pull"3. Second lines, marks, and overlays on a group
A group tab holds more than a name. Three options add to it, and the tab grows to hold them without ever covering the icon or the text.
| Option | What it adds | Example |
|---|---|---|
sub="..." | A second line under the name, such as an address range or a plan | group web "Web tier" type=web-tier sub="10.0.1.0/24" { |
stack=a,b | Up to three small marks under that, written like the marks of a node | group plan "Plan" type=service-plan stack=simple:dotnet { |
overlay | A dashed frame around nodes or groups that the overlay does not own | overlay set "Web machines" type=scale-group members=w1,w2,w3 |
An overlay is the answer to "these machines are one scaling group, but they sit in two zones". Write the nodes in their own groups, then write one overlay line after them that lists the members. When all the members share one group, the overlay is laid out as a frame of its own. When they sit in different groups, the frame is drawn around them after layout and crosses the group frames on purpose. If the frame would also surround a node that is not a member, validate_diagram returns warning W206 with the three fixes.
flow "Overlay across two zones" desc="Two web machines in two zones are framed as one scaling group." direction=rightgroup a "Zone a" type=zone { node w1 service "Web 1"}group b "Zone b" type=zone { node w2 service "Web 2"}overlay set "Web machines" type=scale-group sub="At least 2" members=w1,w2Nodes:
- Availability zone: Zone a
- Web 1, service
- Availability zone: Zone b
- Web 2, service
Overlays:
- Scale group overlay: Web machines (At least 2), around Web 1, Web 2
Connections:
An edge between two nodes that sit side by side, such as a primary and a replica database, is drawn straight across, so the two columns stay level. Give it ..> and a label such as "replication". Keep to one such pair in a diagram.
See also
| Doc | Why |
|---|---|
| Frames, tones, lines, and symbols | Every mark and option drawn beside its source |
| Generic and technology icons | Every simple mark, drawn |
| Examples | Marks, overlays, and event edges in complete diagrams |
| Cloud architecture | The five-step recipe |
| Writing diagrams | Node and group options in the whole language |