# Marks, second lines, and overlays

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

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](https://docs.plotwork.dev/cloud-architecture/lines-and-symbols.md).

## 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.

```plotwork
node app storage "Web app" icon=azure:blob-storage stack=simple:angular,simple:typescript
node api service "Orders API" icon=azure:app-service stack=simple:dotnet
```

Use a mark for the technology of the code, not for the cloud product, which already has its icon.

**Diagram source**

```diagram
flow "Marks on two services" desc="A web app with Angular and TypeScript marks calls an API with a .NET mark." direction=right
node app storage "Web app" icon=azure:blob-storage stack=simple:angular,simple:typescript
node api service "Orders API" icon=azure:app-service stack=simple:dotnet
app -> api : "HTTPS"
```

*Picture: Marks on two services: 2 nodes, 1 connection. A web app with Angular and TypeScript marks calls an API with a .NET mark.*

**Text description**

**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.

```plotwork
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.

**Diagram source**

```diagram
flow "Overlay across two zones" desc="Two web machines in two zones are framed as one scaling group." direction=right
group 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,w2
```

*Picture: Overlay across two zones: 2 nodes, 0 connections. Two web machines in two zones are framed as one scaling group.*

**Text description**

**Nodes:**

- 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](https://docs.plotwork.dev/cloud-architecture/lines-and-symbols.md) | Every mark and option drawn beside its source |
| [Generic and technology icons](https://docs.plotwork.dev/cloud-icons/generic.md) | Every `simple` mark, drawn |
| [Examples](https://docs.plotwork.dev/cloud-architecture/examples.md) | Marks, overlays, and event edges in complete diagrams |
| [Cloud architecture](https://docs.plotwork.dev/cloud-architecture.md) | The five-step recipe |
| [Writing diagrams](https://docs.plotwork.dev/writing-diagrams.md) | Node and group options in the whole language |