# Groups and overlays

> Page: https://docs.plotwork.dev/reference/language/groups. Index of every page: https://docs.plotwork.dev/llms.txt

How a group frames nodes and nested groups, the options it takes, and how an overlay draws a frame around members that layout placed apart.

## TL;DR

| Question | Answer |
|---|---|
| How is a group written? | `group <id> "Name" type=<type> provider=<provider> sub="10.0.0.0/16" {`, its nodes, then `}` on its own line. |
| Which options does a group take? | `type`, `provider`, `icon`, `tone`, `sub`, `stack`. |
| How do I set the provider for the whole diagram? | Write `provider=` on the flow header; nested groups inherit it. |
| How is an overlay written? | `overlay <id> "Name" members=<id>,<id>`, one line, after its members. |

## Flow groups

A group draws a frame around nodes and nested groups. It is written `group <id> "Name" type=<type> provider=<provider> sub="10.0.0.0/16" {`, then its nodes, then `}` on its own line. `type=` says what the group is, from the closed list on the [group types page](https://docs.plotwork.dev/reference/language/group-types.md); the type gives the group an icon, a tone, and a frame style, and a group nested inside another is shaded one step stronger than the one around it, in light and in dark. `icon=` and `tone=` are optional overrides. The frame carries a corner tab in its top-left corner, which holds the group's icon and its name on one line. The tab grows to fit the name with the same padding on both sides, and a name longer than the widest node card is cut with an ellipsis and warning `W203`. `sub=` adds a short second line under the name, such as a network address, and `stack=` puts up to three small marks under that, such as a lock for a network rule or a technology logo. The tab grows to hold both and never covers its own icon. A group with no `type=` whose name gives its type for certain takes it: a name that is or ends with `VPC`, `Network`, `Subnet`, `Kafka`, `Queue`, `Event bus`, `Kubernetes`, `Region`, `AWS account`, `Data`, `Security`, `IAM`, or `Monitoring`, a name that is exactly `Production`, `Staging`, `Dev`, `Pipeline` or `Cluster`, or a region code such as `us-east-1` or `westeurope`. "Data science team" and "Data pipeline" stay plain. `type=none` keeps a group plain, and `icons=off` on the header turns this off. A group with no type and no icon shows only its name. `icon=none` removes any icon. An edge that passes under a tab goes behind it.

| Option | Values | Effect |
|---|---|---|
| `type` | `cloud`, `account`, `region`, `zone`, `network`, `subnet`, `public-subnet`, `private-subnet`, `management-subnet`, `isolated-subnet`, `resource-group`, `cluster`, `scale-group`, `service-plan`, `web-tier`, `app-tier`, `data-tier`, `storage-account`, `messaging`, `edge`, `security`, `identity-boundary`, `trust-boundary`, `observability`, `ci-cd`, `environment`, `cloud-boundary`, `on-premises`, `client-side`, `external-systems` | What the group is. It sets the default icon, tone, and frame style. An unknown value is error `E124` with the nearest type. |
| `provider` | `aws`, `gcp`, `azure`, `alibaba`, `oci`, `ibm`, `cloudflare`, `digitalocean`, `vercel` | Whose resources the group holds, so its type draws that provider's icon: `type=network provider=aws` draws `aws:vpc`. Nested groups inherit it. Write `provider=` on the flow header to set it for the whole diagram. |
| `icon` | `set:name` or `none` | The icon in the tab, for example `aws:cloud`. It overrides the icon of the type. |
| `tone` | `neutral`, `blue`, `violet`, `aqua`, `orange`, `green`, `amber`, `red` | Tints the frame, the tab, and the border. It overrides the tone of the type. A group with no type is `neutral`. |
| `sub` | quoted text | A short second line in the tab under the name, such as an address range or a plan name. A line longer than the widest card is cut with an ellipsis and warning `W203`. |
| `stack` | up to 3 icon references, separated by commas | Small marks in the tab, written like the marks of a node: `stack=lucide:lock,simple:terraform`. |

**Diagram source**

```diagram
flow "Typed groups" provider=aws direction=down

group account "Production" type=account {
  group region "eu-west-1" type=region {
    group vpc "Application VPC" type=network {
      node fn function "Handler" icon=aws:lambda
    }
  }
}
```

*Picture: Typed groups: 1 node, 0 connections.*

**Text description**

**Nodes:**

- Account: Production
  - Region: eu-west-1
    - Virtual network: Application VPC
      - Handler, function

**Connections:**

## Overlays

An overlay draws a dashed frame around nodes or groups it does not own, wherever layout put them: a scaling group that spans two zones, or a redundant set of machines inside a tier. It is one line, `overlay <id> "Name" members=<id>,<id>`, written after the members, and it takes the same look options as a group: `type`, `provider`, `icon`, `tone`, `sub`, `stack`. A dashed frame around nodes or groups it does not own, wherever layout puts them: a scaling group across two zones, or a redundant set inside a tier. Write it after the members, one line: overlay id "Name" members=a,b type=scale-group. Use a group when the frame should own what is inside it.

- When every member sits in one group, the overlay is laid out as a frame of its own, so layout leaves room for its edge and tab and nothing can fall inside by accident.
- When members sit in different groups, nothing moves: the frame is drawn around them after layout, above the group frames it crosses and below the edges and nodes. Its tab never touches a group tab, another overlay tab, a node, or an edge label: it slides along the top edge to a free stretch, and when there is none the frame grows by the same amount on every side until the tab clears them.
- A frame that would also surround a node that is not a member is warning `W206`, with the three fixes: add the node to `members=`, put the members in one group one after another, or split the overlay in two.
- A member must exist (`E137`), be listed once, not be an overlay, not sit inside another member (`E138`), and belong to no other overlay (`E139`).
- Edges connect nodes, never an overlay or a group.

**Diagram source**

```diagram
flow "Redundant set" direction=down

group tier "Web tier" type=web-tier sub="10.0.1.0/24" {
  node lb gateway "Load balancer"
  node w1 service "Web 1"
  node w2 service "Web 2"
  node w3 service "Web 3"
}
overlay set "Web machines" type=scale-group members=w1,w2,w3

lb -> w1
lb -> w2
lb -> w3
```

*Picture: Redundant set: 4 nodes, 3 connections.*

**Text description**

**Nodes:**

- Web tier: Web tier (10.0.1.0/24)
  - Load balancer, gateway
  - Web 1, service
  - Web 2, service
  - Web 3, service

**Overlays:**

- Scale group overlay: Web machines, around Web 1, Web 2, Web 3

**Connections:**

- Load balancer to Web 1
- Load balancer to Web 2
- Load balancer to Web 3

## See also

| Doc | Why |
|---|---|
| [Language reference](https://docs.plotwork.dev/reference/language.md) | Every page of the reference and what each covers |
| [Group types](https://docs.plotwork.dev/reference/language/group-types.md) | The closed list `type=` takes, with the frame and icon of each |
| [Cloud architecture](https://docs.plotwork.dev/cloud-architecture.md) | Typed groups, provider icons, and how to map a product name to an icon |
| [Marks, second lines, and overlays](https://docs.plotwork.dev/cloud-architecture/marks-and-overlays.md) | The same features drawn and explained by example |