|
| 1 | +--- |
| 2 | +adr: "0033" |
| 3 | +status: Accepted |
| 4 | +date: 2026-07-16 |
| 5 | +tags: [clients, mobile, server, sdk] |
| 6 | +--- |
| 7 | + |
| 8 | +# 0033 - Adopt Mermaid diagram standard |
| 9 | + |
| 10 | +<AdrTable frontMatter={frontMatter}></AdrTable> |
| 11 | + |
| 12 | +## Context and problem statement |
| 13 | + |
| 14 | +Architecture diagrams are scattered across tools and formats with no organizational standard: |
| 15 | +Draw.io XML, Lucidchart embeds, ad hoc Mermaid, and images committed without source. The same system |
| 16 | +is drawn differently in different spaces with no mechanism to keep representations consistent and |
| 17 | +diagrams rot because nothing connects them to the systems they describe. Finally, AppSec's |
| 18 | +Engagement Model requires system representations that today are rebuilt from scratch per review. |
| 19 | + |
| 20 | +A prior initiative reached proof of concept on Structurizr, a dedicated C4 modeling platform, with |
| 21 | +an on-prem instance and SSO integration underway. SecOps eventually raised concerns about its |
| 22 | +maintenance posture and missing compliance documentation which caused a re-evaluation of the choice. |
| 23 | +Also, hosting a separate platform added operational overhead. Finally, experience with the PoC |
| 24 | +showed that structurizr and all modeling tools' central promise -- one model producing many |
| 25 | +audience-specific views -- requires substantial rework per audience in practice. |
| 26 | + |
| 27 | +## Considered options |
| 28 | + |
| 29 | +- **Status quo:** every team picks its own tool. |
| 30 | +- **Structurizr (self-hosted):** shared C4 model platform; deprioritized for the reasons above. |
| 31 | +- **IcePanel:** visual C4 SaaS; no diagrams-as-code model for version control. |
| 32 | +- **draw.io as the standard:** strongest native Confluence app, but stores XML in attachments and |
| 33 | + has no GitHub-native rendering. |
| 34 | +- **Mermaid with defined conventions:** text in Markdown, GitHub-native rendering, macro support on |
| 35 | + Confluence, and zero infrastructure. |
| 36 | + |
| 37 | +## Decision outcome |
| 38 | + |
| 39 | +Chosen option: **Mermaid with defined conventions**, published as the |
| 40 | +[diagram standard](../../contributing/diagrams.md) on the contributing site. The standard is the |
| 41 | +living reference and its rules evolve by PR without superseding this decision. This ADR is |
| 42 | +superseded only if the chosen option itself changes. A snapshot of the rules at adoption: |
| 43 | + |
| 44 | +1. Diagrams are Mermaid source text, nothing else: as Mermaid code blocks, or, if in Confluence, via |
| 45 | + Macro Pack's Mermaid diagram in text-input mode. |
| 46 | +2. Any Mermaid diagram type that fits. |
| 47 | +3. A diagram lives in the doc it illustrates, not a separate file. |
| 48 | +4. Every diagram carries a perspective caption: audience, intent, and scope. |
| 49 | +5. A diagram answers one question at one altitude. Anything larger requires multiple diagrams. |
| 50 | +6. C4 is shared vocabulary only. No C4 tooling is adopted. |
| 51 | +7. A diagram is owned by whoever owns the doc it lives in. |
| 52 | +8. A diagram updates with the change it depicts. AI instruction files carry the obligation of |
| 53 | + establishing a standing safeguard. |
| 54 | + |
| 55 | +### Positive consequences |
| 56 | + |
| 57 | +- Diagram sources are diffable, reviewable in PRs, readable by AI agents, and free of hosted |
| 58 | + platforms and new vendors. |
| 59 | +- One notation and one vocabulary across repos, the contributing site, and Confluence, with a |
| 60 | + mechanical ingestibility test (`GET /wiki/api/v2/pages/{id}?body-format=storage` returns the raw |
| 61 | + Mermaid) guarding the Confluence path. |
| 62 | +- Mermaid encourages small, single-purpose, and digestible diagrams, which rule 5 codifies. |
| 63 | + |
| 64 | +### Negative consequences |
| 65 | + |
| 66 | +- **rustdoc does not render Mermaid**; crate READMEs embedded via `include_str!` show the raw source |
| 67 | + as a plain code block. This is accepted. If rendering ever becomes necessary, |
| 68 | + [aquamarine](https://github.com/mersinvald/aquamarine) is the chosen path in inline mode only. It |
| 69 | + is not adopted now because it adds a proc-macro dependency to the security-critical SDK workspace |
| 70 | + for cosmetic gain. |
| 71 | +- **Macro Pack authoring is slow.** Macro Pack is the standard for now. If authoring friction |
| 72 | + warrants a replacement, trial weweave's "Mermaid Charts & Diagrams" (runner-up: the official |
| 73 | + Mermaid Chart app) and gate any adoption on the storage-format ingestibility test above. |
| 74 | +- **Mermaid's C4 diagram types are experimental** and auto-layout limits complex diagrams. Rule 5 |
| 75 | + keeps each diagram inside what auto-layout handles well, and rule 2's open-ended diagram types |
| 76 | + provide the fallback. |
| 77 | +- **A rendered diagram shared as an image loses its perspective**, since the caption attaches in the |
| 78 | + doc rather than inside the Mermaid source (embedding was tested and fails to render on Macro |
| 79 | + Pack). This is accepted. |
| 80 | + |
| 81 | +### Plan |
| 82 | + |
| 83 | +The standard is published at Contributing › Diagrams, and the bulk of the contributing site's |
| 84 | +existing diagrams (PlantUML/Kroki sources, static diagram assets, and source-less images) have been |
| 85 | +converted to comply, so the site becomes the reference implementation of the standard, with the |
| 86 | +exceptions noted below. Elsewhere, legacy diagrams convert when their docs are next touched: images |
| 87 | +and non-Mermaid sources in repos become Mermaid code blocks, and Confluence attachments and images |
| 88 | +become Macro Pack's Mermaid diagram in text-input mode. |
| 89 | + |
| 90 | +The remaining adoption work is delegated to its owners: |
| 91 | + |
| 92 | +- The architecture team authors the initial system context and container diagrams for the site's |
| 93 | + Architecture section, since none exist today, and validates the standard end to end with a pilot |
| 94 | + domain diagram set. |
| 95 | +- Owning teams add perspective captions to the converted site diagrams and to the existing in-repo |
| 96 | + Mermaid diagrams, since the conversion was faithful to originals that carried none. |
| 97 | +- The Autofill team redraws the overlay architecture and messaging diagrams as several purpose-built |
| 98 | + diagrams, because the current pair crams a whole subsystem into one picture and cannot be |
| 99 | + converted mechanically. The overlay SVGs remain on the site as a tracked deviation until the |
| 100 | + replacements ship. The team also refreshes the Collecting Page Details deep dive, whose content |
| 101 | + predates Manifest v3, and re-derives its diagrams afterward. |
0 commit comments