Skip to content

Standardize technical diagrams at Bitwarden - #835

Merged
MGibson1 merged 2 commits into
mainfrom
arch/adr/documentation-standards-adr-only
Jul 20, 2026
Merged

Standardize technical diagrams at Bitwarden#835
MGibson1 merged 2 commits into
mainfrom
arch/adr/documentation-standards-adr-only

Conversation

@MGibson1

Copy link
Copy Markdown
Member

📔 Objective

ADR only branch from #834.

(cherry picked from commit bf1e723)

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.

📸 Screenshots

@MGibson1
MGibson1 requested a review from a team as a code owner July 20, 2026 19:27
@github-actions github-actions Bot added the adr label Jul 20, 2026
@github-actions

github-actions Bot commented Jul 20, 2026

Copy link
Copy Markdown
Contributor

🤖 Bitwarden Claude Code Review

Overall Assessment: APPROVE

This PR adds a single ADR (0033) that adopts a Bitwarden-wide diagram standard: Mermaid source in Markdown, one diagram per audience/intent/scope, sources living beside the docs they illustrate. It is the "ADR only" split from #834. The document follows the established ADR frontmatter and structure conventions, and the new record is auto-listed via <DocCardList /> so no index changes are required. The only concern is that the ADR's central reference link points to a file introduced by the sibling PR.

Code Review Details

@cloudflare-workers-and-pages

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

Copy link
Copy Markdown

Deploying contributing-docs with  Cloudflare Pages  Cloudflare Pages

Latest commit: 9a99c83
Status: ✅  Deploy successful!
Preview URL: https://f8f36479.contributing-docs.pages.dev
Branch Preview URL: https://arch-adr-documentation-stand-9ffg.contributing-docs.pages.dev

View logs

## Decision outcome

Chosen option: **Mermaid with defined conventions**, published as the
[diagram standard](../../contributing/diagrams.md). The standard is the living reference. Its rules

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

QUESTION: This links to ../../contributing/diagrams.md, which does not exist in this branch — it is introduced by the sibling PR #834.

Details

The "Decision outcome" frames this link as the standard's "living reference" — the document that actually holds the rules this ADR adopts. In this PR's tree, docs/contributing/diagrams.md is absent, so:

If #835 is intended to merge before #834, is that ordering acceptable, or should this PR be gated on #834 (or merged together) so the reference resolves on the live site?

@MGibson1
MGibson1 requested a review from a team as a code owner July 20, 2026 20:19
@MGibson1
MGibson1 force-pushed the arch/adr/documentation-standards-adr-only branch from ab7953e to 9a99c83 Compare July 20, 2026 20:31

@withinfocus withinfocus left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can nitpick some language but not a big deal.

@MGibson1
MGibson1 merged commit cd70039 into main Jul 20, 2026
13 checks passed
@MGibson1
MGibson1 deleted the arch/adr/documentation-standards-adr-only branch July 20, 2026 20:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants