Skip to main content

ADR-007: Mermaid-as-Code with CI Compilation Gate

  • Status: Accepted
  • Date: 2026-08-12

Context & Problem Statement​

Architecture diagrams stored as binary images (PNG, JPEG, draw.io XML) cannot be diffed, reviewed, or automatically updated in Git pull requests. Furthermore, image diagrams quickly drift from source code implementations.

Decision​

All system diagrams in DOCCAD are authored as Mermaid-as-code:

  • Shared diagrams reside as .mmd files in docs/diagrams/**.
  • One-off illustrations are authored as fenced ```mermaid code blocks directly in Markdown/MDX.
  • In the prototype, diagrams are rendered and syntax-checked at static build time via @docusaurus/theme-mermaid with securityLevel: 'strict'; standalone headless mermaid-cli verification in CI is planned (P1-08).
  • AI modifications to diagrams occur strictly through UpdateMermaidDiagram task contracts.