Skip to content

ADR-0010: Mermaid over D2/Kroki for architecture diagrams

Status

Accepted — 2026-04-02

Context

Architecture diagrams need to be versioned as code and auto-rendered in documentation. D2 via Kroki was trialled across multiple versions (v0.4 through v0.5). Documentation has since migrated from MkDocs Material to Azure DevOps Wiki.

Decision

Mermaid for all architecture diagrams. No Kroki container.

Rationale

  • Mermaid renders natively in ADO Wiki and MkDocs — zero extra infrastructure
  • Kroki required a sidecar container, LAN build-time dependency, pip plugin
  • D2 produced better visuals but operational overhead not justified
  • ADO Wiki renders Mermaid fenced code blocks out of the box

Alternatives considered

  • D2 via Kroki: better visuals, rejected — build-time container dependency
  • Raw SVG: best quality, rejected — manual maintenance breaks CI
  • DrawIO: good quality, rejected — manual export step

Consequences

  • All diagrams in Mermaid inside markdown files
  • No Kroki container in Docker stack
  • Revisit D2 via Kroki at Phase 3+ as a proper ADO pipeline build stage if visual quality becomes insufficient