mdd
DocsUse CasesGitHubOpen App

Architecture diagrams that live in AGENTS.md

Every agent-assisted repo has a context file — AGENTS.md, CLAUDE.md — that humans and agents both read. An mdd diagram there is context engineering: the ASCII orients the human, and the JSON beside it is ground truth your agent can parse, validate, and update as the code changes.

Open AppRead the Docs

A service map in AGENTS.md

A small service architecture as it appears spliced into AGENTS.md. The fenced ASCII is generated — never hand-drawn — from the JSON model your agent edits.

<!-- mdd:begin id=arch src=docs/architecture.diagram.json -->
```

            ┌────────────┐
            │ Web Client │
            └──────┬─────┘
                   │
                   │
            ┌──────▼──────┐
            │ API Gateway │
            └──────┬──────┘
         ┌─────────┴────────┐
         │                  │
 ┌───────▼──────┐   ┌───────▼───────┐
 │ Auth Service │   │ Order Service │
 └───────┬──────┘   └───────┬───────┘
         └──────┐           ├──┐
                ├───────────┘  │
          ┌─────▼────┐   ┌─────▼─────┐
          │ Postgres │   │ Job Queue │
          └──────────┘   └───────────┘

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

The model your agent edits

{
  "version": 1,
  "boxes": [
    {
      "id": "web",
      "label": "Web Client",
      "row": 0,
      "connections": [
        {
          "to": "api",
          "arrow": "to"
        }
      ]
    },
    {
      "id": "api",
      "label": "API Gateway",
      "row": 1,
      "connections": [
        {
          "to": "auth",
          "arrow": "to"
        },
        {
          "to": "orders",
          "arrow": "to"
        }
      ]
    },
    {
      "id": "auth",
      "label": "Auth Service",
      "row": 2,
      "connections": [
        {
          "to": "db",
          "arrow": "to"
        }
      ]
    },
    {
      "id": "orders",
      "label": "Order Service",
      "row": 2,
      "connections": [
        {
          "to": "db",
          "arrow": "to"
        },
        {
          "to": "queue",
          "arrow": "to"
        }
      ]
    },
    {
      "id": "db",
      "label": "Postgres",
      "row": 3
    },
    {
      "id": "queue",
      "label": "Job Queue",
      "row": 3
    }
  ]
}

Your agent draws it, you review it

  1. Sketch the system as JSON — boxes, rows, connections. Your agent can draft it from the code.
  2. Run mdd render to splice the diagram into AGENTS.md. The splice is idempotent: regenerating never touches surrounding prose.
  3. When the architecture changes, the agent edits the JSON and re-renders. mdd check in CI fails if the ASCII ever goes stale.
  4. You review the diagram in the diff, like any other change.

A prompt to hand your agent

Maintain the architecture diagram in AGENTS.md with mdd. The source of truth is docs/architecture.diagram.json. After changing it, run: npx mdd render --json docs/architecture.diagram.json --file AGENTS.md --id arch — then commit both files.

Why mdd here

Mermaid in AGENTS.md is an opaque code fence to anyone reading the file in a terminal or diff — and to the agent it is a string, not a model. mdd keeps a JSON model the agent edits with a validation loop (--format json) and ASCII output that renders identically everywhere the context file is read.

More use cases