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
.mmdfiles indocs/diagrams/**. - One-off illustrations are authored as fenced
```mermaidcode blocks directly in Markdown/MDX. - In the prototype, diagrams are rendered and syntax-checked at static build time via
@docusaurus/theme-mermaidwithsecurityLevel: 'strict'; standalone headlessmermaid-cliverification in CI is planned (P1-08). - AI modifications to diagrams occur strictly through
UpdateMermaidDiagramtask contracts.