mdd
DocsUse CasesGitHubOpen App

Runbook flowcharts that render in a terminal at 3am

Failure maps and decision trees live in Git and get read over SSH mid-incident — where a Mermaid fence is opaque. SRE and platform teams get plain Unicode that works in cat, less, and a pager, from a JSON model simple enough for an incident bot to first-draft.

Open AppRead the Docs

A paging decision flow

A first-response decision flow with a decision diamond, as it appears in a runbook read from the terminal.

<!-- mdd:begin id=checkout-5xx src=runbooks/checkout-5xx.diagram.json -->
```

            ┌─────────────────────┐
            │ Pager: checkout 5xx │
            └──────────┬──────────┘
                       │
                       │
                 ╱─────▼────╲
                ⟨ LB errors? ⟩
                 ╲─────┬────╱
           ┌────yes────┴────no────┐
           │                      │
 ┌─────────▼────────┐   ┌─────────▼─────────┐
 │ Roll back deploy │   │ Check DB failover │
 └──────────────────┘   └───────────────────┘

```
[diagram source](runbooks/checkout-5xx.diagram.json)
<!-- mdd:end -->

The model your agent edits

{
  "version": 1,
  "boxes": [
    {
      "id": "page",
      "label": "Pager: checkout 5xx",
      "row": 0,
      "connections": [
        {
          "to": "lb",
          "arrow": "to"
        }
      ]
    },
    {
      "id": "lb",
      "label": "LB errors?",
      "row": 1,
      "shape": "diamond",
      "connections": [
        {
          "to": "rollback",
          "arrow": "to",
          "label": "yes"
        },
        {
          "to": "db",
          "arrow": "to",
          "label": "no"
        }
      ]
    },
    {
      "id": "rollback",
      "label": "Roll back deploy",
      "row": 2
    },
    {
      "id": "db",
      "label": "Check DB failover",
      "row": 2
    }
  ]
}

Your agent draws it, you review it

  1. Model the decision flow as JSON — a diamond is one property on a box.
  2. Splice it into the runbook with mdd render; the block renders in every terminal.
  3. After each incident, the postmortem's action items update the JSON, and the flow re-renders in place.
  4. mdd check keeps every runbook's diagram in sync with its model.

A prompt to hand your agent

Update the decision flow in runbooks/checkout-5xx.md when this runbook changes. Edit runbooks/checkout-5xx.diagram.json, then run: npx mdd render --json runbooks/checkout-5xx.diagram.json --file runbooks/checkout-5xx.md --id checkout-5xx.

Why mdd here

A runbook diagram that only renders on a docs site is useless during the incident that needs it. mdd's output is the artifact itself — plain aligned Unicode in the Markdown — so it degrades nowhere, and decision diamonds give flowchart semantics without a rendering engine.

More use cases