Clusters and Groups

What this page covers

This page explains how to group related nodes in DiagramFlow. It covers titled and untitled clusters, the group(...) form, styling attributes, assigned containers, and nesting.

Mental model

Clusters and groups are visual containers. They help you show that a set of nodes belongs together, such as a subsystem, bounded context, worker pool, data domain, or deployment area.

Use them when structure matters more than listing every node at the top level. In architecture diagrams, that usually makes the system easier to scan.

Basic syntax

The most common pattern is a titled cluster:

cluster("Data") {
    queue = SQS("queue")
}

You can also create a cluster without a visible title:

cluster() {
    worker = ECS("worker")
}

Attributes and options

cluster("...") { ... }

Use a titled cluster when the group itself should communicate meaning:

cluster("Workers") {
    worker = ECS("worker")
}

group("...") { ... }

group(...) is useful when you want the same grouping idea with a different keyword:

group("Workers") {
    worker = ECS("worker")
}

api = EKS("api")
api -> worker

Visual attributes

Cluster and group definitions can include visual attributes:

Example with multiple attributes:

cluster(
    "Data Domain",
    bgcolor="#E0F2FE",
    color="#0284C7",
    fontcolor="#0C4A6E",
    style="filled,rounded",
    border_style="solid"
) {
    queue = SQS("queue")
    handler = Lambda("handler")
}

Common patterns

Assigned cluster or group

You can assign a cluster to a variable and use that container as a connection endpoint:

source = EKS("source")
workers = cluster("Workers") {
    ECS("worker-1")
    ECS("worker-2")
}

source -> workers

This is useful when you want to show traffic flowing to a subsystem instead of a single inner node.

Cluster style combinations

You can combine style and border_style in the same definition:

cluster("Data", style="filled,rounded", border_style="dashed") {
    queue = SQS("queue")
}

Nested clusters

Clusters can be nested when you need to show hierarchy:

source = EKS("source")
cluster("Outer") {
    cluster("Inner") {
        queue = SQS("queue")
    }
}

source -> queue

Nested containers are helpful for large systems, but they are easier to read when kept shallow.

Recommended usage

• Use clusters and groups to show architecture structure, not just decoration.
• Prefer short, meaningful titles such as Workers, Data, Ingestion, or Public API.
• Use assigned clusters when the relationship is really to the whole subsystem, not a specific inner node.
• Keep styling consistent across the same diagram so containers feel related.
• Use nesting only when it adds clarity. Too many layers make diagrams harder to read.

Common mistakes

• Adding clusters only for visual decoration when they do not communicate a real subsystem boundary.
• Nesting containers too deeply and making the architecture harder to scan.
• Styling each cluster differently without a semantic reason, which turns the diagram into a legend problem.

Related docs

• Quickstart
• Diagram Configs
• Nodes
• Connections