Skip to content
Documentation

ADR-0002 Client-Side Diagram Rendering

Status

Section titled “Status”

Accepted

Context

Section titled “Context”

The documentation site requires diagrams to explain architecture and security postures. Installing native binaries (e.g., D2 CLI) in Docker complicates the toolchain and may not be compatible with Cloudflare Pages.

Decision

Section titled “Decision”
  • Render Mermaid and D2 diagrams client-side using their JavaScript/WASM bundles.
  • Do not introduce build-time diagram generation or Docker-installed binaries.

Rationale

Section titled “Rationale”
  • Keeps Docker image minimal and fast to rebuild.
  • Aligns with Cloudflare Pages static hosting capabilities.
  • Simplifies developer onboarding and avoids cross-platform compilation issues.

Consequences

Section titled “Consequences”
  • Diagrams rely on client JavaScript; printing and accessibility require periodic review.
  • Runtime rendering adds minor client-side processing time.
  • Build artifacts remain lightweight, but screenshots or PDFs require manual workflow.

Deferred Considerations

Section titled “Deferred Considerations”
  • Server-side rendering or pre-generated SVGs if accessibility requirements demand it.
  • Possible caching strategies if diagram count grows significantly.

Implementation Steps

Section titled “Implementation Steps”
  1. Maintain Mermaid and D2 integrations configured in astro.config.mjs.
  2. Store diagrams as MDX pages under apps/docs/src/content/docs/diagrams.
  3. Validate diagrams locally using the Docker environment and the dev server.

Verification Method

Section titled “Verification Method”
  • pnpm build:docs succeeds without requiring native binaries.
  • Deployed docs render diagrams correctly in modern browsers.
  • Accessibility reviews confirm diagrams have appropriate textual context.