Circuitry Logo
Circuitry
Open Circuitry

Sequence Diagrams

Draw how a system behaves — who acts, in what order — and hand the same picture to the agent so you are both working from one agreed description instead of a paragraph of prose.

Most of what goes wrong in software with more than one moving part is not a wrong value inside one function. It is order and ownership: a step taken by the wrong participant, or taken before it was allowed. That is very hard to see in a chat message and very easy to see in a diagram.

So Circuitry gives you the diagram as a first-class thing you can draw, edit, name, keep, and read back. You draw it, or the agent draws it, and either way it stays on the canvas as an object — not a picture pasted into a conversation that scrolls away.

Where they live

A sequence diagram is drawn on a Workflow canvas — which includes a whiteboard, since a whiteboard is a workflow document with no nodes running on it yet. That means the diagram gets everything the canvas already has: label editing, the Style panel, the selection toolbar, undo, copy and paste into another document, and the drawing layer if you want to annotate it by hand.

The parts of a diagram

PartWhat it is
Laneone participant — a header box with a lifeline running down from it
Actora participant drawn as a stickman with its name above it, for a person or a system outside the one you are describing
Messagea labelled arrow from one lifeline to another, with a dot on each
Replythe same thing drawn dashed, for a response coming back
Self messagea small box on one lifeline, for a participant acting on itself
Notea document-shaped box beside a lifeline, for something that isn't a message
Framea labelled box drawn around a run of messages — a loop, a branch, an optional step
Name labelthe diagram's name, above its lanes, with an optional details row under it
Findings legenda box under the diagram holding Observations and Recommendations

Rows read top to bottom in the order the messages happen.

Four participants, the order of the exchange between them, and an alt frame for the two ways it can go. Nothing here says how any of it is built — that is the point.

Draw one by hand

1. Make the first participant

Add a Flow node to the canvas — drag it from the node palette, or press Space and search for it. A Flow node is the plain labelled box; see Adding & Connecting Nodes.

Select it and press Add lane in the selection toolbar. The box becomes a participant: it keeps its name, gains a lifeline below it, and the canvas is now a sequence diagram.

The button only appears on a Flow node that isn't already part of a diagram — so it's an invitation once, not clutter forever.

For a person, drop an Actor instead. Expand the Flow shapes in the node palette and drag Actor from the Structure row. It lands as a stickman with its name above it and its lifeline already below — the same participant, drawn as a human rather than a box. Use it for whoever is outside the system: the customer, the operator, the third party you call.

2. Use the diagram tools

As soon as the canvas holds a diagram, a diagram toolbar appears down the left side. It behaves like the drawing toolbar: it parks itself behind a small edge tab and slides out when you hover or tap it, so a narrow screen keeps its canvas.

Each entry is a mode, like a pen. Pick it, make one gesture, and it hands back to the pointer — which means every one of them works with a single finger, a pencil or a mouse, with no multi-select anywhere.

  • Lane — tap the canvas for a new participant there; it joins a nearby header row.
  • Message — drag from one lifeline to another; the new arrow's label opens for typing.
  • Note — tap a lifeline for a note at that height.
  • loop — drag a box over some messages to wrap them in a loop frame.
  • alt — the same, for a branch with alternatives.
  • opt — the same, for a step that may not happen.
  • par — the same, for things happening at once.

Dragging a message between two different diagrams merges them into one.

3. Add messages from a lifeline

You don't have to switch tools to add one more message. Press and hold a lifeline (touch or pencil), or right-click it (mouse), and a menu offers each other participant twice:

  • Message to … — a solid arrow
  • Reply to … — the same arrow, dashed

The message lands level with where you pressed, everything below renumbers, and the new arrow's label opens for typing straight away.

4. Edit what you've selected

Select any part of the diagram and the selection toolbar changes to match it.

  • A message — its arrow or either of its dots: Rename, Reply (or Message to turn it back from dashed to solid), Frame, Delete.
  • A note or a self message: Rename, Frame, Delete.
  • Several messages or notes at once: Frame, Delete.
  • A lane — its header or its lifeline: Rename, Message, Note, Name diagram (only until the diagram has a name), Delete lane.
  • A frame: Rename, Remove frame.
  • The findings legend: Collapse or Expand, and Clear findings.

Frame is a group button: it opens onto the six frame kinds — loop, alt, opt, par, critical and break. The four on the toolbar are the common ones; all six are here.

Deleting a lane's last message leaves the lane standing, because a participant with nothing to do yet is a normal thing to have half-way through drawing.

5. Name it

Press Name diagram on a selected lane and a name label appears above the lanes. Drag that label and the whole diagram moves with it.

Press and hold — or right-click — the label for its own menu:

  • Rename
  • Show details / Hide details — the small row under the name
  • Fit to view — zoom the canvas to this diagram

The details row is filled in for you. It carries the latest result or status line the diagram was given, when it was last updated, what version of the code it was checked against, and how many measured timings it holds. It's the diagram's own provenance, visible without opening anything.

Several diagrams on one canvas

Once a diagram has a name, you can put another one beside it. This is the point of naming: scenarios sit side by side and can be compared. "Dial at home" next to "Dial on cellular" next to "Dial from a café" — same participants, different behaviour, all in view at once.

Every one of them is independent. Renaming, dragging, editing or deleting one leaves the others exactly where they are.

Let the agent draw it

Ask for it in plain words — "draw the sequence for what happens when the phone reconnects" — and the agent draws it onto the canvas you have open, then fits the view to it. If you have no workflow or whiteboard document open, it will ask you to open one; it won't create a document behind your back.

Two things make this more than a picture.

It can read the diagram back. Every diagram on the canvas has a written form, and the agent re-derives that text from the canvas each time it looks — so it reads your renames, your dragging, and anything drawn by an earlier session or by a colleague, not a stale copy it is holding. You never have to type that text yourself, and you never have to keep it in sync.

That makes the diagram memory. A chat thread scrolls away and a new session starts cold. A named diagram on a canvas doesn't: the next session reads it back and picks up where the last one left off, including its findings and its timings. Several named diagrams are several remembered scenarios.

The agent can also point at things. Ask which step it means and it selects that message on the canvas, so you're looking at the same arrow rather than guessing from a description. It removes things by name and step number for the same reason — "delete step 4 of Dial on cellular", never by some internal identifier you can't see.

Sequence diagrams aren't the only kind. Flowcharts and state diagrams can be drawn the same way, laid out in a clear area of the canvas.

The working loop

This is the part that changes how the work goes.

1. Design the system as a diagram. Before any code, agree the participants, the messages, and who owns each decision. Argue about the diagram — it is much cheaper to move an arrow than to move a subsystem.

2. Build it. The diagram is the brief. Hand it to the agent as the thing to implement.

3. Validate the code against the diagram. Ask the agent to walk the written code and check it against each step: does this actually happen in this order, and is it this participant that decides? Reading code tells you the sequence it intends. The diagram is what you agreed it should perform. The gap between those two is where the bugs are.

4. Keep the diagram as the reference. Not a design artefact you throw away — the thing you come back to. Ask the agent to stamp it with which files it was checked against and which version of the code, so that later you can tell whether the code has moved underneath it.

Debugging with diagrams

When something breaks in a system with several parts, the useful question is rarely what value was wrong — it's what happened, in what order, and on whose side. A diagram of a real run answers that; a stack trace usually doesn't.

Put logging in every part of the system. Every participant — each client, each server, each device, the browser, the companion Circuit — should record what it did and when. The goal is that a field test can be reconstructed afterwards from the logs alone. A part with no logging is a lane you can't draw.

Then run it, and have the agent draw what happened. Ask it to gather the logs from every actor and either draw a new diagram of that run, or annotate the existing design diagram with what actually occurred. You are not asking for an opinion; you are asking for the events, in order, with the times.

Compare runs under different conditions. The same scenario at home, on cellular, and from a remote network, drawn side by side as named diagrams, shows you which step diverges and when. A problem that only appears on one network is a problem you can see the moment two diagrams are next to each other.

What gets filled in for you

You ask; the agent reads the logs and fills these in:

  • Timings. A measured duration appears beside the message it belongs to. The diagram's details row counts how many it holds. Ask for a fresh analysis and the timings update in place — nothing moves.
  • Observations. What the evidence shows, one sentence each, tied to a step — "message 6: the connection closed 21 seconds after it opened". They render as a legend under the diagram.
  • Recommendations. What to change, in the same legend, so the state of play is visible at a glance to you and to any later session.
  • A result line. A pass/fail or test stamp that shows in the details row under the name.

This one is a run, not a design: every duration under a message was measured, and the legend underneath is what the evidence showed and what to do about it. Both of you can read it, and so can the next session.

Each pass makes the picture clearer to both of you. That is the actual value: an agent asked cold about a multi-part failure tends to produce a confident, plausible, wrong answer, and then a fix for it. An agent working from a diagram of what measurably happened, refined over a few runs, finds the stable fix instead — because the picture is where the disagreement between what you expected and what occurred becomes impossible to miss.

A repeating flicker, storm or race is almost always a missing owner — two parts both deciding the same thing — rather than something to be smoothed out with a delay. A diagram makes that obvious, because two lanes are visibly taking the same decision.

Related