mdd
DocsUse CasesGitHubOpen App

Sequence diagrams your agent cannot misdraw

Call flows are the diagram agents reach for most — auth handshakes, API chains, incident timelines — and the one they mangle worst when drawing characters by hand. In mdd a sequence diagram is a list of participants and an ordered list of messages: message order in the JSON is the layout, there are no layout decisions to get wrong, and the ASCII renders in READMEs, design docs, diffs, and terminals.

Open AppRead the Docs

A login flow in a design doc

A login handshake as it appears spliced into a design doc: an actor, solid calls, dashed replies, and a self-message. The JSON lists participants left to right and messages in time order — the engine does the rest.

<!-- mdd:begin id=login-flow src=docs/login-flow.diagram.json -->
```
   o              ┌─────┐      ┌──────────┐     ┌──────────┐
  /|\             │ App │      │ Auth API │     │ Sessions │
  / \             └─────┘      └──────────┘     └──────────┘
 User                │               │                │
   │                 │               │                │
   │   POST /login   │               │                │
   │────────────────▶│               │                │
   │                 │               │                │
   │                 │ verify(creds) │                │
   │                 │──────────────▶│                │
   │                 │               │                │
   │                 │               │ create session │
   │                 │               │───────────────▶│
   │                 │               │                │
   │                 │               │   session id   │
   │                 │               │◀┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄│
   │                 │               │                │
   │                 │               │ sign JWT       │
   │                 │               │──┐             │
   │                 │               │◀─┘             │
   │                 │               │                │
   │                 │     token     │                │
   │                 │◀┄┄┄┄┄┄┄┄┄┄┄┄┄┄│                │
   │                 │               │                │
   │ Set-Cookie; 302 │               │                │
   │◀┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄│               │                │
   │                 │               │                │
```
[diagram source](docs/login-flow.diagram.json)
<!-- mdd:end -->

The model your agent edits

{
  "version": 1,
  "kind": "sequence",
  "participants": [
    {
      "id": "user",
      "label": "User",
      "actor": true
    },
    {
      "id": "app",
      "label": "App"
    },
    {
      "id": "auth",
      "label": "Auth API"
    },
    {
      "id": "db",
      "label": "Sessions"
    }
  ],
  "messages": [
    {
      "from": "user",
      "to": "app",
      "label": "POST /login"
    },
    {
      "from": "app",
      "to": "auth",
      "label": "verify(creds)"
    },
    {
      "from": "auth",
      "to": "db",
      "label": "create session"
    },
    {
      "from": "db",
      "to": "auth",
      "label": "session id",
      "reply": true
    },
    {
      "from": "auth",
      "to": "auth",
      "label": "sign JWT"
    },
    {
      "from": "auth",
      "to": "app",
      "label": "token",
      "reply": true
    },
    {
      "from": "app",
      "to": "user",
      "label": "Set-Cookie; 302",
      "reply": true
    }
  ]
}

Your agent draws it, you review it

  1. List the participants left to right and the messages top to bottom — the behavior reads as JSON in the order it happens. Your agent can draft it from a code trace.
  2. Run mdd render to splice the diagram into the doc; columns widen so labels always fit.
  3. When the flow changes, the agent inserts or reorders messages and re-renders — reordering a JSON array, never redrawing arrows.
  4. mdd check in CI fails if the rendered flow ever goes stale relative to the model.

A prompt to hand your agent

Maintain the login-flow sequence diagram in docs/auth.md with mdd. The source of truth is docs/login-flow.diagram.json (kind: "sequence" — participants left-to-right, messages in time order). After changing it, run: npx mdd render --json docs/login-flow.diagram.json --file docs/auth.md --id login-flow — then commit both files.

Why mdd here

Sequence diagrams are where hand-drawn ASCII fails hardest: every inserted message shifts every line below it, and a model eyeballing characters misaligns arrowheads and lifelines. In mdd the message array is the timeline — inserting a step is a one-line JSON edit, the engine recomputes every column and row, and call vs. reply is semantic (reply: true), not a hand-picked glyph.

More use cases