Everything ArchStep, from a first diagram to Mermaid import.

Every .step file starts with one architecture block declaring the nodes on the canvas. Each node has a kind, a name, and a mandatory position — Step uses fixed, explicit coordinates rather than auto-layout, so the diagram looks the same every time you open it.

architecture {
  service User at (0, 0)
  service API at (220, 0)
  database Orders at (220, 200)
}

scenario Overview {
  User -> API: "GET /orders"
  API -> Orders: "read"
}

Three node kinds are supported: service, database, and queue — each renders with its own icon so the canvas reads at a glance. There's no fourth kind and no custom-icon system; open an issue if you need one.

A scenario block is the sequence itself: one edge (A -> B) per line, in order, each occupying one tick of playback. Add an optional : "label" to show what's actually being sent.

Wrap edges in parallel { } and they all fire on the same tick — real fan-out/fan-in, not several edges that merely happen to be drawn close together.

architecture {
  service API at (0, 0)
  queue Kafka at (220, 0)
  service Worker1 at (440, -80)
  service Worker2 at (440, 80)
}

scenario Notify {
  API -> Kafka: "publish"
  parallel {
    Kafka -> Worker1
    Kafka -> Worker2
  }
}

A state KEY = "value" step doesn't draw an edge — it sets a value in the data tracker, a small legend overlaid on the canvas (top-right) showing what data looks like at this point in the sequence. The row that just changed highlights in amber.

architecture {
  service Checkout at (0, 0)
  service Warehouse at (220, 0)
}

scenario Reserve {
  Checkout -> Warehouse: "reserve"
  state CART = "[A, B]"
}

Need two values to change together, on the same tick? Use a state { } block instead of separate lines — every key inside it updates (and highlights) simultaneously.

state {
  CACHE_HITS = "1"
  ORDER = "{id: 123, status: pending}"
}

One architecture block can back several scenario blocks — the Editor and this demo player both show a scenario tab bar whenever a file defines more than one. Useful for e.g. a Login and Logout flow over the same set of services. See the examples gallery for a worked one.

In the Editor, drag any node and its new (x, y) is written straight back into the .step source — the diagram and the text never fall out of sync. (In these docs demos dragging moves the node visually but won't persist — try it live in the Editor.)

The Mermaid Import page converts a Mermaid sequenceDiagram straight to an ArchStep canvas, with a tab to peek the generated source. It supports:

• participant / actor, declared or implicit from first use
• all message arrows (->>, -->>, -x, …), with or without a label
• par / and / end → a Step parallel { } block (one message per branch)
• title → the scenario name

Anything else — loop, alt/opt, Note, or a non-sequence diagram type like classDiagram — fails with a specific, line-numbered error instead of silently dropping information.

The Editor is a Monaco pane with Step syntax highlighting. A compile error underlines the exact line in red — the same message also appears in the error panel — so you don't have to hunt for a typo across a long file.

architecture {
  service|database|queue <Name> at (<x>, <y>)
}

scenario <Name> {
  <Node> -> <Node>
  <Node> -> <Node>: "label"
  parallel { <edge> <edge> ... }
  state <KEY> = "value"
  state { <KEY> = "value"  <KEY2> = "value2" }
}

// line comments are supported anywhere