Nodes and groups

Nodes are addressable architectural entities. Groups are labeled containment boundaries. Together they describe the components and scopes visible in a diagram.

Nodes

A node requires a globally unique identifier and a visible label. The identifier is used by edges and layout statements but is never rendered. A label contains 1 to 60 Unicode scalar values.

stack 1.0

diagram "Node example" {
  node api "Public API" {
    kind service
    detail "Order orchestration"
  }
}

Two nodes may share a visible label when they are distinct entities, though labels should remain understandable without relying on position. A node block cannot repeat kind, icon, or detail.

Node kinds

kind provides coarse architectural meaning. It also selects a theme-controlled shape and fallback icon. The default is service.

Kind	Intended meaning
actor	Person, role, team, or autonomous participant
client	Browser, mobile app, desktop app, device, or other client
service	Long-running application, API, gateway, or general component
function	On-demand or serverless compute unit
worker	Background processor or scheduled job
database	Durable, queryable datastore
cache	Datastore whose contents are disposable or derived
queue	Queue, stream, bus, or broker for asynchronous delivery
storage	Blob, object, file, or archival storage
external	System outside the architecture's control boundary

Kinds are semantic categories, not vendor shapes. A hosted PostgreSQL instance is still a database; name the technology in detail.

Labels and details

detail is an optional visible second line of 1 to 80 Unicode scalar values. Use it for one technology or a short responsibility, such as "Next.js", "PostgreSQL 17", or "Order orchestration". It remains visible in every rendered diagram and is never reduced to tooltip-only content.

Labels and details are plain text, not Markdown or HTML. An explicit icon decorates the node but does not change its kind, identity, or accessible label. See Themes and icons.

Groups

A group has a globally unique identifier, a label of 1 to 60 Unicode scalar values, and at least one descendant node. It may contain nodes, nested groups, and one layout block.

stack 1.0

diagram "Boundaries" {
  group platform "Platform" {
    group data "Data layer" {
      node primary "Primary database" {
        kind database
      }
    }
  }
}

Group nesting can reach three levels below the diagram. A node belongs to its nearest group and all ancestor groups. Because declarations cannot be reused, a node cannot belong to two separate groups.

Edges are always declared at diagram scope, and only nodes can be edge endpoints. A group does not create an implicit node or relationship. Its label explains whether the boundary represents a system, domain, network, deployment area, team, or another concern; containment alone does not imply runtime isolation, security, ownership, or deployment semantics.