mdd
DocsUse CasesGitHubOpen App

Diagrams that survive ten rounds of design review

In an RFC or ADR the diagram is the part reviewers argue about — and redraw. Staff engineers sketch intent, the agent drafts the doc, and mdd regenerates the ASCII in place on every revision, so the diagram stays reviewable in plain diffs and terminal-based review where images and Mermaid fences cannot follow.

Open AppRead the Docs

A pipeline in an RFC

A processing pipeline with a cluster boundary, as it appears in a design doc. Each revision edits the JSON; the ASCII is always regenerated, never patched.

<!-- mdd:begin id=pipeline src=docs/rfc-012-pipeline.diagram.json -->
```

          ┌────────────┐
          │ Ingest API │
          └──────┬─────┘
          ┌──────┴──────┐
          │             │
   ┌┄ ingest pipeline ┄┄┼┄┄┄┄┄┄┐
   ┆ ┌────▼───┐   ┌─────▼────┐ ┆
   ┆ │ Parser │   │ Enricher │ ┆
   ┆ └────┬───┘   └─────┬────┘ ┆
   └┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┘
          │             │
          ├─────────────┘
   ┌──────▼──────┐
   │ Event Store │
   └──────┬──────┘
          │
          │
    ┌─────▼─────┐
    │ Query API │
    └───────────┘

```
[diagram source](docs/rfc-012-pipeline.diagram.json)
<!-- mdd:end -->

The model your agent edits

{
  "version": 1,
  "boxes": [
    {
      "id": "ingest",
      "label": "Ingest API",
      "row": 0,
      "connections": [
        {
          "to": "parse",
          "arrow": "to"
        },
        {
          "to": "enrich",
          "arrow": "to"
        }
      ]
    },
    {
      "id": "parse",
      "label": "Parser",
      "row": 1,
      "connections": [
        {
          "to": "store",
          "arrow": "to"
        }
      ]
    },
    {
      "id": "enrich",
      "label": "Enricher",
      "row": 1,
      "connections": [
        {
          "to": "store",
          "arrow": "to"
        }
      ]
    },
    {
      "id": "store",
      "label": "Event Store",
      "row": 2,
      "connections": [
        {
          "to": "query",
          "arrow": "to"
        }
      ]
    },
    {
      "id": "query",
      "label": "Query API",
      "row": 3
    }
  ],
  "clusters": [
    {
      "id": "pipeline",
      "label": "ingest pipeline",
      "members": [
        "parse",
        "enrich"
      ]
    }
  ]
}

Your agent draws it, you review it

  1. Sketch the system as JSON while drafting the doc — or have your agent draft both.
  2. Splice the diagram into the RFC with mdd render.
  3. Each review round edits the JSON model; re-rendering is idempotent, so prose around the block never churns.
  4. Reviewers see the diagram change as a readable diff, not a binary image swap.

A prompt to hand your agent

This RFC's diagram is maintained with mdd. To change it, edit docs/rfc-012-pipeline.diagram.json, then run: npx mdd render --json docs/rfc-012-pipeline.diagram.json --file docs/rfc-012.md --id pipeline.

Why mdd here

Design docs are co-authored and heavily revised; hand-drawn ASCII breaks on the second edit and Mermaid is unreviewable in a terminal. mdd's idempotent splice means ten revision rounds produce ten clean diagram diffs, and cluster boxes mark the zones reviewers care about.

More use cases