System

A system diagram explains how a set of components fit together: the components, the boundaries they sit in, and the links between them.

Scope

system is a conceptual architecture diagram for prose — the picture in a report, design document or study note that answers "what are the parts, which ones belong together, and what passes between them". It is not a deployment, network or runtime specification:

  • Components and links are only the ones you declare. There are no ports, protocols, sizes, coordinates or routes in the source; the engine places everything.
  • A group is a boundary (a zone, a plane, a team, a pod). Groups nest at most two deep — a group inside a group.
  • A link says what connects two components, and may carry a short label. Whether it is solid or dashed comes from its relation, not from a style field.
  • One diagram holds at most 16 nodes, 6 groups and 24 links. Past that, a diagram stops being readable at a glance; split it into two diagrams, one per concern. Exceeding a limit is a validation error.

If the diagram needs sequence ordering, entity relationships, class structure or a network topology with addresses, use an engineering tool such as Mermaid, D2 or PlantUML.

Choosing between system and another kind

A diagram has one kind. Pick the first line that fits:

The relationship is…Use
a single line of steps in orderflow
one centre with items radiating from ithub_spoke
the stages of one thing's life, moving between statesstate
a tree — every item has one parenthierarchy
anything else: components in boundaries, or linked in more than a treesystem

Fields

FieldRequiredTypeDescription
kindyes"system"Must be exactly "system"
titlenostringRendered above the diagram
groupsnoarray of GroupBoundaries. At most 6
nodesyesarray of NodeComponents. At least 2, at most 16
linksnoarray of LinkConnections. At most 24

Group fields

FieldRequiredTypeDescription
idyesstringUnique across all groups and nodes
labelyesstringDisplay text
parentnostringid of the group this one sits inside. Nesting is at most two deep

Node fields

FieldRequiredTypeDescription
idyesstringUnique across all groups and nodes
labelyesstringDisplay text
groupnostringid of the group the node sits in
rolenostring"store" (data is kept here — a database, queue or file store), "external" (outside your control), "actor" (a person or client acting on the system). Omit for an ordinary component
emphasisnostring"primary" or "secondary" — see Schema
statusnostring"success", "normal", "warning" or "critical" — see Schema
FieldRequiredTypeDescription
fromyesstringid of a node or a group
toyesstringid of a node or a group
labelnostringWhat passes along the link
directionnostring"forward" (default, from → to), "both", or "none" (an association)
relationnostring"direct" (default — a call, a data flow) or "indirect" (asynchronous, optional or conditional)

A link to a group ends at the group's boundary — use it for "the whole zone talks to X". A link cannot join a group to something inside it, and cannot join an end to itself (a state that loops back is a state diagram).

Rules

  • Node and group ids share one namespace; each must be unique.
  • group and parent must name an existing group; from and to must name an existing node or group.
  • Every link needs two different ends, neither inside the other.
  • The engine chooses the layout. It lays each group out first and then treats it as one box, so boxes never overlap; links run along horizontal and vertical lines and go around components, not through them, and each link label is set on a free stretch of its link. Every label is set whole — a label too long for a box makes the box wider — and render_diagnosed reports the rare label that still had to be shrunk or cut. A group label is set on one line, at most about 320 px wide, and a link label at most about 180 px.

Example

Zero Trust Architecture System: Control plane (Policy decision point, Identity, device state, threat intelligence, logs), Data plane (Subject: user or device, Policy enforcement point, Enterprise resource). Links: Policy engine ↔ Policy administrator; Identity, device state, threat intelligence, logs → Policy engine; Subject: user or device → Policy enforcement point; Policy enforcement point → Enterprise resource; Policy administrator → Policy enforcement point (allow / deny); Policy enforcement point → Policy administrator (access request) [indirect]. Zero Trust Architecture Control plane Policy decision point Data plane Policyengine Policyadministrator Identity, device state,threat intelligence, logs Subject: useror device Policy enforcementpoint Enterpriseresource allow / deny access request

A link to a whole group:

Function point measurement boundary System: Application being measured (ILF: internal logical file), User, EIF: external interface file, kept by another system. Links: User → Application being measured (EI (input)); Application being measured → User (EO (derived output)); EIF: external interface file, kept by another system → Application being measured (reference) [indirect]. Function point measurement boundary Application being measured User ILF: internallogical file EIF: external interface file,kept by another system EI (input) EO (derived output) reference

Label capacity

How long a label can be before the engine sets it smaller, wraps it, or cuts it short with "…". Each number is measured by rendering a small reference declaration with a growing label and reading the diagnostics render_detailed returns, so the table always agrees with them. Lengths are in characters written without spaces: Hangul syllables are one em wide, Latin lowercase letters about half that. unchanged is the longest label shown at the usual size on one line; whole is the longest shown without "…". A slot's width depends on its siblings, so read a number as a guide for the reference declaration named in the second column and use declart validate --strict for the declaration itself.

A dash means the engine reports nothing for the slot up to 120 characters. That is not a promise that any length fits: a slot the engine does not fit at all draws a long label past the picture without a warning.

SlotMeasured inHangul (unchanged / whole)Latin (unchanged / whole)
groups[].label2 groups, 2 nodes, 1 link22 / 3242 / 60
nodes[].label3 nodes, 2 links30 / 4228 / 79
links[].label3 nodes, 2 links15 / 2128 / 40

Schema

What a declaration of this kind may contain, as declart schema and schema() report it. The value lists and counts are the ones the parser checks, and a test holds every field, count and rule to the parser in both directions, so a declaration written to this page parses. The prose above is the explanation; this is the reference.

Fields

FieldTypeRequiredValues / meaning
kindenumyessystem
titlestringno

groups — 0 to 6 elements

FieldTypeRequiredValues / meaning
idstringyesa short name to refer to the group by
labelstringyes
parentreferencenothe id of the group this one sits inside

nodes — 2 to 16 elements

FieldTypeRequiredValues / meaning
idstringyesa short name to refer to the node by
labelstringyes
groupreferencenothe id of the group the node sits in
roleenumnostore, external, actor
emphasisenumnoprimary, secondary
statusenumnosuccess, normal, warning, critical

links — 0 to 24 elements

FieldTypeRequiredValues / meaning
fromreferenceyesthe id of a node or a group
toreferenceyesthe id of a node or a group
labelstringno
directionenumnoforward, both, none
relationenumnodirect, indirect

Rules

  • node ids and group ids are unique, all in one set
  • parent names another group's id, never the group itself
  • groups nest two deep at most (a group inside a group)
  • group names a group's id
  • from and to name the id of a node or a group
  • a link joins two different ends
  • a link does not join a group to something inside it