Mermaid ADR approval and site implementation by MGibson1 · Pull Request #834 · bitwarden/contributing-docs

MGibson1 · 2026-07-20T18:32:36Z

📔 Objective

Adopts a Bitwarden-wide diagram standard: Mermaid source in Markdown, one diagram per audience/intent/scope, sources living beside the docs they illustrate.

Motivation (from ADR 0033 in this PR):

Architecture diagrams are scattered across tools and formats — Draw.io XML, Lucidchart embeds, ad hoc Mermaid, images committed without source. The same system is drawn differently in different places, there is no mechanism to keep representations consistent, and diagrams rot because nothing connects them to the systems they describe.
AppSec's Engagement Model needs system representations that today are rebuilt from scratch per review.
The Structurizr PoC was deprioritized: SecOps flagged its maintenance posture and missing compliance documentation, hosting a separate platform added operational overhead, and the one-model-many-views promise required substantial rework per audience in practice.

What this PR contains:

The living diagram standard ADR 0033 (Standardize technical diagrams at Bitwarden #835) points to.
Docusaurus wiring for the Mermaid theme (with an icon pack) and removal of the Kroki plugin.
Direct-translation conversion of existing PlantUML/Kroki diagrams to Mermaid across the contributing site.
A simplified EDD state-machine diagram, replacing the JPG asset (and the associated .drawio / .png / .gif files) with inline Mermaid.

Suggested Review Guidelines

This is a big PR, I know. Please read the ADR and Diagram Standard carefully. They're concise and important. Everything else is updating diagrams to comply with these standards (with the exception writing perspectives).

Use the below link table to review diagram updates for accuracy. Meaningful changes have been made to EDD and push notifications, please give those added attention.

📸 Screenshots

Old vs. new for each converted or adjusted page.

Diagrams	New (preview)	Original (production)
Clients — data model (1)	preview	prod
Clients — overview / State Service (1)	preview	prod
Clients — package diagram (1)	preview	prod
Clients — service implementation (4)	preview	prod
SDK — architecture overview (1)	preview	prod
SDK — crate structure (1)	preview	prod
SDK — data models (1)	preview	prod
SDK — Secrets Manager (1)	preview	prod
Deep dive — IPC (4)	preview	prod
Deep dive — passkeys FIDO2 overview (1)	preview	prod
Deep dive — passkeys browser extension (1)	preview	prod
Deep dive — push notifications, mobile (4)	preview	prod
Deep dive — push notifications, non-mobile (2)	preview	prod
Deep dive — autofill messaging API (1)	preview	prod
Deep dive — autofill collect page details (6)	preview	prod
Contributing — Angular component diagrams (2)	preview	prod
Contributing — EDD refactoring phases (1, redrawn)	preview	prod
Diagram standard — example perspective diagram (1, new page)	preview	— (new page)

withinfocus

Let's split the ADR and plan from the application.

github-actions · 2026-07-20T19:18:02Z

🤖 Bitwarden Claude Code Review

Overall Assessment: APPROVE

Reviewed the Mermaid diagram-standard adoption: ADR 0033 acceptance, the new Contributing › Diagrams standard page, Docusaurus wiring (theme-mermaid, ELK layout, an inline bw icon pack), removal of the Kroki plugin, and the bulk conversion of PlantUML/Kroki diagrams to Mermaid across the site. Verified the substantive content changes (EDD state machine, batched backfill script, and push-notification sequences) for correctness and confirmed the Kroki removal is complete with no orphaned references or code blocks.

Code Review Details

No new findings. Notes on prior review threads (already resolved by the author):

The infinite-loop risk in the EDD transition backfill is fixed — the batched WHILE loop now guards with WHERE email IS NULL AND username IS NOT NULL.
The orphaned types/remark-kroki.d.ts shim was removed, and docusaurus.config.js no longer references remark-kroki.
AppSec review for the new @docusaurus/theme-mermaid and @mermaid-js/layout-elk dependencies was confirmed by a maintainer in an existing thread (reviewed, approved, no VULN task required).

Verified independently:

No remaining kroki type=plantuml / @startuml blocks in docs/, and no lingering remark-kroki/kroki references outside the lock file — the conversion and removal are complete.
package.json and package-lock.json are consistent; @mermaid-js/layout-elk is pinned to an exact 0.1.9.
The new docs/contributing/diagrams.md is picked up by the autogenerated contributing sidebar, so no sidebars.js change is needed.

Dependency Changes

Package	Change	Ecosystem
`@docusaurus/theme-mermaid`	New (3.10.1)	npm
`@mermaid-js/layout-elk`	New (0.1.9)	npm
`remark-kroki`	Removed	npm

MGibson1 · 2026-07-20T19:18:07Z

Let's split the ADR and plan from the application.

not sure what you mean by this. Are you saying to split the diagram updates from the ADR?

withinfocus · 2026-07-20T19:21:21Z

Let's split the ADR and plan from the application.

not sure what you mean by this. Are you saying to split the diagram updates from the ADR?

Yes. We want to merge the ADR in a Proposed status before Council.

cloudflare-workers-and-pages · 2026-07-20T20:54:29Z

Deploying contributing-docs with Cloudflare Pages

Latest commit:	`ff92bac`
Status:	⚡️ Build in progress...

View logs

theMickster

A couple improvements requested and one question. great start!

This is a toy example where, presumably, `username` had a NOT NULL constraint as the real `email` column does, but this makes it explicit that these are concerns for these kinds of migrations.

withinfocus

Still a draft technically, but saw a few tweaks.

withinfocus · 2026-07-22T16:11:17Z

+# Diagram standard
+
+**Audience:** Bitwarden engineers, contributors, and AI agents authoring or reading diagrams
+anywhere Bitwarden documents its systems.
+
+## Notation
+
+- The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in
+  [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
+


⛏️ This is rather "official" to me and comes off as a bit too formal. It's a bit AI-like too, as if it's instructions with the all-caps language. We aren't writing a spec here as I see it.

The notation section also has a single bullet point that renders awkwardly.

Both of these things hint at an upcoming documentation standard I have drafted, but split this out of for speed.

Adopting a well known standard for communication is in line with our standards best practices, RFCs do this for a reason to be explicit about what is allowed or required. This phrasing is basically the same as the RFC it references.

Removing the single bullet feels fine, it's a holdover from when there were more and because the draft documentation standard does have multiple

withinfocus · 2026-07-22T16:12:32Z

+sidebar_position: 2
+---
+
+# Diagram standard


🎨 I think this can just be "Diagrams".

It's called that because it's referenced as a standard in the ADR and I'd like it to be seen as one. things that go against this doc go against "the standard"

claude · 2026-07-22T22:30:52Z

GHSA-w5hq-g745-h8pq

+    "@docusaurus/theme-mermaid": "3.10.1",
    "@mdx-js/react": "3.1.0",
+    "@mermaid-js/layout-elk": "0.1.9",


❓ QUESTION: Was AppSec approval obtained for the new @docusaurus/theme-mermaid and @mermaid-js/layout-elk dependencies?

Context

These are net-new dependencies (replacing remark-kroki). Bitwarden's Dependency Review and Approval process asks that new dependencies go through AppSec review before integration, and the PR description does not reference a VULN task or approval. Both are first-party official packages (MIT-licensed per the lockfile), so this is likely low-risk — just confirming the process was followed or intentionally waived for this internal docs site.

Ran this through a security review directly. Low risk on the two direct packages.

Direct packages (both green):

@docusaurus/theme-mermaid@3.10.1 — MIT, first-party Docusaurus org, version-locked to @docusaurus/core@3.10.1 already in the tree. No install scripts.

@mermaid-js/layout-elk@0.1.9 — MIT, official Mermaid-JS org. Note it's pre-1.0 (0.x), so API stability isn't guaranteed.

Licensing: layout-elk pulls in elkjs@0.9.3, which is EPL-2.0 (Eclipse Public License, weak copyleft), not MIT. For a docs site consuming the unmodified npm package at build time this is fine, but it's a different license class worth noting for the record.

The actual change is transitive: the two-line package.json diff drives +1151/-200 in the lockfile, nearly all of it mermaid@11.16.0 and its subtree (dompurify, katex, cytoscape, d3, marked, roughjs, uuid@14.0.1, and more). That subtree is the attack-surface change, not the two direct adds.

Vuln scan: no open Dependabot alert touches the new subtree. The one open uuid advisory (GHSA-w5hq-g745-h8pq, affects < 11.1.1) doesn't apply here, since mermaid resolves uuid@14.0.1.

Reviewed and approved. The direct packages are first-party and low-risk, the EPL-2.0 transitive is acceptable for build-time use on an internal docs site, and the new subtree carries no open advisories. No VULN task required for this one.

withinfocus

One minor correction Claude found, but then I can approve.

Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

withinfocus

Great change showing Mermaid usage!

github-actions Bot added the adr label Jul 20, 2026

withinfocus requested changes Jul 20, 2026

View reviewed changes

Comment thread docs/architecture/adr/0033-adopt-the-diagram-standard.md Outdated

Comment thread docs/architecture/adr/0033-adopt-the-diagram-standard.md Outdated

MGibson1 marked this pull request as ready for review July 20, 2026 19:17

MGibson1 requested review from a team as code owners July 20, 2026 19:17

claude Bot reviewed Jul 20, 2026

View reviewed changes

Comment thread docs/architecture/clients/services/implementation.md Outdated

MGibson1 mentioned this pull request Jul 20, 2026

Standardize technical diagrams at Bitwarden #835

Merged

MGibson1 marked this pull request as draft July 20, 2026 20:19

MGibson1 added 5 commits July 20, 2026 13:51

Establish diagram standard and add mermaid theme to comply with it

0c697b6

accept diagram standards ADR 0033

c0ee3de

Convert direct-translation plantuml diagrams to mermaid

d9eec19

Simplify EDD diagram story

d1eae78

Remove kroki

465befb

MGibson1 force-pushed the arch/adr/documentation-standards branch from 8b5e95b to 465befb Compare July 20, 2026 20:54

theMickster requested changes Jul 22, 2026

View reviewed changes

MGibson1 added 4 commits July 22, 2026 07:38

Fixup: base services are abstract, not interfaces

b20e461

Fixup: pin dependencies

42f95c3

Fixup: kroki is no longer a dependency

af9c9c9

fixup: toy example previously could loop forever

87a95d8

This is a toy example where, presumably, `username` had a NOT NULL constraint as the real `email` column does, but this makes it explicit that these are concerns for these kinds of migrations.

MGibson1 requested review from theMickster and withinfocus July 22, 2026 15:56

withinfocus reviewed Jul 22, 2026

View reviewed changes

Update ADR references

fa406d2

MGibson1 marked this pull request as ready for review July 22, 2026 16:43

MGibson1 requested a review from withinfocus July 22, 2026 20:05

grammatical improvements

4c6ea68

withinfocus added the ai-review Request a Claude code review label Jul 22, 2026

claude Bot reviewed Jul 22, 2026

View reviewed changes

Comment thread docs/architecture/adr/0033-adopt-mermaid-diagram-standard.md Outdated

claude Bot reviewed Jul 22, 2026

View reviewed changes

withinfocus requested changes Jul 22, 2026

View reviewed changes

Update docs/architecture/adr/0033-adopt-mermaid-diagram-standard.md

7cf0600

Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

MGibson1 requested a review from withinfocus July 22, 2026 22:57

theMickster approved these changes Jul 23, 2026

View reviewed changes

withinfocus approved these changes Jul 23, 2026

View reviewed changes

withinfocus changed the title ~~Arch/adr/documentation standards~~ Mermaid ADR approval and site implementation Jul 23, 2026

Merge branch 'main' into arch/adr/documentation-standards

ff92bac

MGibson1 merged commit 386dcf4 into main Jul 23, 2026
9 of 10 checks passed

MGibson1 deleted the arch/adr/documentation-standards branch July 23, 2026 21:31

Uh oh!

Conversation

MGibson1 commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📔 Objective

Suggested Review Guidelines

📸 Screenshots

Uh oh!

withinfocus left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 Bitwarden Claude Code Review

Dependency Changes

Uh oh!

MGibson1 commented Jul 20, 2026

Uh oh!

Uh oh!

withinfocus commented Jul 20, 2026

Uh oh!

cloudflare-workers-and-pages Bot commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying contributing-docs with Cloudflare Pages

Uh oh!

theMickster left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

withinfocus left a comment

Choose a reason for hiding this comment

Uh oh!

withinfocus Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

withinfocus Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

MGibson1 Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

withinfocus Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

MGibson1 Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

claude Bot Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

withinfocus Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

withinfocus left a comment

Choose a reason for hiding this comment

Uh oh!

withinfocus left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

MGibson1 commented Jul 20, 2026 •

edited

Loading

github-actions Bot commented Jul 20, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Jul 20, 2026 •

edited

Loading