From db1c9ceb21a6364063890b987c90dbc0a3a6a686 Mon Sep 17 00:00:00 2001 From: Matt Gibson Date: Mon, 20 Jul 2026 10:34:36 -0700 Subject: [PATCH 1/2] Standardize technical diagrams at Bitwarden (cherry picked from commit bf1e7235f93f03c7e1dbcb1a2ee03be3bf80b280) --- .../adr/0033-adopt-the-diagram-standard.md | 81 +++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 docs/architecture/adr/0033-adopt-the-diagram-standard.md diff --git a/docs/architecture/adr/0033-adopt-the-diagram-standard.md b/docs/architecture/adr/0033-adopt-the-diagram-standard.md new file mode 100644 index 000000000..11b4ae9f3 --- /dev/null +++ b/docs/architecture/adr/0033-adopt-the-diagram-standard.md @@ -0,0 +1,81 @@ +--- +adr: "0033" +status: Proposed +date: 2026-07-16 +tags: [clients, mobile, server, sdk] +--- + +# 0033 - Adopt the diagram standard + + + +## Context and problem statement + +Architecture diagrams are scattered across tools and formats with no organizational standard: +Draw.io XML, Lucidchart embeds, ad hoc Mermaid, and images committed without source. The same system +is drawn differently in different spaces with no mechanism to keep representations consistent and +diagrams rot because nothing connects them to the systems they describe. Finally, AppSec's +Engagement Model requires system representations that today are rebuilt from scratch per review. + +A prior initiative reached proof of concept on Structurizr, a dedicated C4 modeling platform, with +an on-prem instance and SSO integration underway. SecOps eventually raised concerns about its +maintenance posture and missing compliance documentation which caused a re-evaluation of the choice. +Also, hosting a separate platform added operational overhead. Finally, experience with the PoC +showed that structurizr and all modeling tools' central promise -- one model producing many +audience-specific views -- requires substantial rework per audience in practice. + +## Considered options + +- **Status quo:** every team picks its own tool. +- **Structurizr (self-hosted):** shared C4 model platform; deprioritized for the reasons above. +- **IcePanel:** visual C4 SaaS; no diagrams-as-code model for version control. +- **draw.io as the standard:** strongest native Confluence app, but stores XML in attachments and + has no GitHub-native rendering. +- **Mermaid with defined conventions:** text in Markdown, GitHub-native rendering, macro support on + Confluence, and zero infrastructure. + +## Decision outcome + +Chosen option: **Mermaid with defined conventions**, published as the +[diagram standard](../../contributing/diagrams.md). The standard is the living reference. Its rules +evolve by PR without superseding this decision and this ADR is superseded only if the chosen option +itself changes. A snapshot of the rules at adoption: + +1. Diagrams are Mermaid source text, nothing else: as Mermaid code blocks, or, if in Confluence, via + Macro Pack's Mermaid diagram in text-input mode. +2. Any Mermaid diagram type that fits. +3. A diagram lives in the doc it illustrates, not a separate file. +4. Every diagram carries a perspective caption: audience, intent, and scope. +5. A diagram answers one question at one altitude. Anything larger requires multiple diagrams. +6. C4 is shared vocabulary only. No C4 tooling is adopted. +7. A diagram is owned by whoever owns the doc it lives in. +8. A diagram updates with the change it depicts. AI instruction files carry the obligation of + establishing a standing safeguard. + +### Positive consequences + +- Diagram sources are diffable, reviewable in PRs, readable by AI agents, and free of hosted + platforms and new vendors. +- One notation and one vocabulary across repos, the contributing site, and Confluence, with a + mechanical ingestibility test (`GET /wiki/api/v2/pages/{id}?body-format=storage` returns the raw + Mermaid) guarding the Confluence path. +- Mermaid encourages small, single-purpose, and digestible diagrams, which rule 5 codifies. + +### Negative consequences + +- **rustdoc does not render Mermaid**; crate READMEs embedded via `include_str!` show the raw source + as a plain code block. This is accepted. If rendering ever becomes necessary, + [aquamarine](https://github.com/mersinvald/aquamarine) is the chosen path in inline mode only. It + is not adopted now because it adds a proc-macro dependency to the security-critical SDK workspace + for cosmetic gain. +- **Macro Pack authoring is slow.** Macro Pack is the standard for now. If authoring friction + warrants a replacement, trial weweave's "Mermaid Charts & Diagrams" (runner-up: the official + Mermaid Chart app) and gate any adoption on the storage-format ingestibility test above. +- **Mermaid's C4 diagram types are experimental** and auto-layout limits complex diagrams. Rule 5 + keeps each diagram inside what auto-layout handles well, and rule 2's open-ended diagram types + provide the fallback. +- **A rendered diagram shared as an image loses its perspective**, since the caption attaches in the + doc rather than inside the Mermaid source (embedding was tested and fails to render on Macro + Pack). This is accepted. +- A migration backlog: the contributing site's PlantUML/Kroki diagrams, static diagram assets, and + source-less images convert to Mermaid. From 9a99c83c01a6303cd02d79b24617064568e550c5 Mon Sep 17 00:00:00 2001 From: Matt Gibson Date: Mon, 20 Jul 2026 12:57:04 -0700 Subject: [PATCH 2/2] push a plan --- custom-words.txt | 8 +++++ ...=> 0033-adopt-mermaid-diagram-standard.md} | 34 +++++++++++++++---- 2 files changed, 35 insertions(+), 7 deletions(-) rename docs/architecture/adr/{0033-adopt-the-diagram-standard.md => 0033-adopt-mermaid-diagram-standard.md} (70%) diff --git a/custom-words.txt b/custom-words.txt index 0e83367e4..b0efcb94b 100644 --- a/custom-words.txt +++ b/custom-words.txt @@ -18,6 +18,8 @@ cryptominer CTAP2 deinitializer deinitializers +deprioritized +diffable dockerized dotfile F-Droid @@ -32,6 +34,7 @@ Hulud Hyperscale iframes inet +ingestibility initialisms IntelliJ Iterm @@ -41,10 +44,12 @@ jumpcloud keychain keypair keyserver +Kroki Kubebuilder LDIF libmagic LLDB +Lucidchart Mailcatcher minio MVVM @@ -76,6 +81,7 @@ roadmaps rollout rollouts Rspack +rustdoc rustup sandboxed SARIF @@ -91,6 +97,7 @@ Sourcery sqlcmd struct structs +Structurizr subfolders subprocessor toolset @@ -102,6 +109,7 @@ typesafe udeps unsynchronized WCAG +weweave Xcodes.app xcworkspace xmldoc diff --git a/docs/architecture/adr/0033-adopt-the-diagram-standard.md b/docs/architecture/adr/0033-adopt-mermaid-diagram-standard.md similarity index 70% rename from docs/architecture/adr/0033-adopt-the-diagram-standard.md rename to docs/architecture/adr/0033-adopt-mermaid-diagram-standard.md index 11b4ae9f3..bf5f3acfc 100644 --- a/docs/architecture/adr/0033-adopt-the-diagram-standard.md +++ b/docs/architecture/adr/0033-adopt-mermaid-diagram-standard.md @@ -5,7 +5,7 @@ date: 2026-07-16 tags: [clients, mobile, server, sdk] --- -# 0033 - Adopt the diagram standard +# 0033 - Adopt Mermaid diagram standard @@ -36,10 +36,10 @@ audience-specific views -- requires substantial rework per audience in practice. ## Decision outcome -Chosen option: **Mermaid with defined conventions**, published as the -[diagram standard](../../contributing/diagrams.md). The standard is the living reference. Its rules -evolve by PR without superseding this decision and this ADR is superseded only if the chosen option -itself changes. A snapshot of the rules at adoption: +Chosen option: **Mermaid with defined conventions**, published as the diagram standard on the +contributing site. The standard is the living reference. Its rules evolve by PR without superseding +this decision and this ADR is superseded only if the chosen option itself changes. A snapshot of the +rules at adoption: 1. Diagrams are Mermaid source text, nothing else: as Mermaid code blocks, or, if in Confluence, via Macro Pack's Mermaid diagram in text-input mode. @@ -77,5 +77,25 @@ itself changes. A snapshot of the rules at adoption: - **A rendered diagram shared as an image loses its perspective**, since the caption attaches in the doc rather than inside the Mermaid source (embedding was tested and fails to render on Macro Pack). This is accepted. -- A migration backlog: the contributing site's PlantUML/Kroki diagrams, static diagram assets, and - source-less images convert to Mermaid. + +### Plan + +[PR #834](https://github.com/bitwarden/contributing-docs/pull/834) publishes the standard at +Contributing › Diagrams and converts the contributing site's existing diagrams (PlantUML/Kroki +sources, static diagram assets, and source-less images) to comply, so the site itself becomes the +reference implementation of the standard. Elsewhere, legacy diagrams convert when their docs are +next touched: images and non-Mermaid sources in repos become Mermaid code blocks, and Confluence +attachments and images become Macro Pack's Mermaid diagram in text-input mode. + +The remaining adoption work is delegated to its owners: + +- The architecture team authors the initial system context and container diagrams for the site's + Architecture section, since none exist today, and validates the standard end to end with a pilot + domain diagram set. +- Owning teams add perspective captions to the converted site diagrams and to the existing in-repo + Mermaid diagrams, since the conversion was faithful to originals that carried none. +- The Autofill team redraws the overlay architecture and messaging diagrams as several purpose-built + diagrams, because the current pair crams a whole subsystem into one picture and cannot be + converted mechanically. The overlay SVGs remain on the site as a tracked deviation until the + replacements ship. The team also refreshes the Collecting Page Details deep dive, whose content + predates Manifest v3, and re-derives its diagrams afterward.