Syntax reference

Overall shape

A remaid file contains exactly one diagram block. Inside, you can mix top-level directives, nodes, edges, groups, and scenes in any order. Whitespace is insignificant; line breaks are stylistic. Comments use // to end of line.

diagram ["title"] {
  // directives
  theme: <theme-id>
  direction: <right|down|left|up>

  // structure
  group <id> ["label"] [{ ... }]
  node  <id> { kind: <kind>, label: "...", parent: <group-id> }
  edge  <id>: <from-node> -> <to-node> [{ label: "..." }]

  // motion (zero or more)
  scene <id> ["label"] {
    loopEvery: <duration>
    <animation> <edge-id> [, <edge-id>...] [{ ... }]
    ...
  }
}

Directives

Directives are document-level settings written as key: value at the top of the diagram body.

theme

Visual theme. Currently only minimal-dark ships. Defaults to minimal-dark.

direction

Layout flow direction. One of right (default), down, left, up.

diagram {
  direction: down
  node a { kind: client,  label: "Client" }
  node b { kind: service, label: "Service" }
  node c { kind: database, label: "DB" }
  edge x: a -> b
  edge y: b -> c
}

Nodes

Syntax: node <id> { ... }. Required property: kind.

Kinds

Five built-in archetypes for v0.1:

• client — browsers, mobile apps, CLIs (any caller).
• service — APIs, microservices, workers, schedulers.
• database — Postgres, MySQL, anything you persist to.
• cache — Redis, Memcached, in-memory stores.
• queue — Kafka topics, RabbitMQ, SQS, message buses.

Node properties

• kind (required) — one of the five above.
• label (optional) — display text. Defaults to the node id. Use a quoted string for anything with spaces or punctuation.
• parent (optional) — id of a group this node belongs to.

Edges

Edges connect two nodes with a direction. Syntax: edge <id>: <from> -> <to> [{ ... }]. Both endpoints must reference existing node ids.

Edge properties

• label (optional) — text rendered as a pill near the edge midpoint. Useful for HTTP verbs, message types, query names.

Groups

Groups are visual containers. Use them to show that several nodes belong to the same logical layer (a microservice cluster, a vendor infrastructure boundary, a deployment unit).

group sdk   "system-param-sdk"
group infra "Consumer's Infrastructure"

node validator { kind: service,  parent: sdk }
node redis     { kind: cache,    parent: infra }

Groups can nest by giving them a parent property themselves. Edges always connect nodes, never groups, and ELK routes them through containers as needed.

Scenes

A scene is one self-contained animation loop. A diagram can have zero or more scenes — they all play simultaneously, each on its own period.

Scene properties

• loopEvery (optional) — duration between repeats. If omitted, remaid uses the natural length of the steps plus a small tail.

Scene steps

Each line inside a scene is one step: <animation> <edge> [, <edge>...] [{ props }]. The four built-in animations and their semantics live on the animations page.

Step properties

• speed — how long the active part of the motion takes. Format: <number>ms or <number>s (e.g. 400ms, 1.5s). Defaults to 600ms.
• after — id of an edge whose most recent step this one should chain after. Resolves to the latest scene step that animated that edge.
• delay — extra offset added on top of after (or t=0 if no after).

Comments

Line comments only. Anything from // to end of line is skipped.

diagram {
  // This whole line is ignored.
  node a { kind: client } // so is this trailing piece
}

Durations

Durations are written as a number followed by a unit. The two units are ms (milliseconds) and s (seconds). The number can have decimals.

• Valid: 400ms, 1s, 1.5s, 250ms
• Invalid: 1m, fast, 0.5