Infrastructure Documentation Redesign Implementation Plan

Created: 2026-03-22 Status: COMPLETE Approved: Yes Iterations: 1 Worktree: No Type: Feature

Summary

Goal: Redesign all architecture documentation pages for readability, accessibility, and dark mode support. Split the monolithic infrastructure page into focused sub-pages, remove hardcoded Mermaid diagram colors, and apply the Vidra brand palette through the global theme system.

Architecture: Remove all inline style directives from Mermaid diagrams and rely on the global Mermaid theme configuration (base theme for light mode, dark theme for dark mode) with CSS refinements. Split infrastructure.md into 5 focused sub-pages organized flat under the Architecture sidebar category.

Tech Stack: Docusaurus 3.9.2, @docusaurus/theme-mermaid, Mermaid.js, CSS custom properties

Scope

In Scope

• Mermaid theme configuration updates in docusaurus.config.ts for proper dark mode switching
• Custom CSS for Mermaid diagram readability (font sizes, spacing, dark mode refinements)
• Redesign of all 8 Mermaid diagrams across overview.md and infrastructure.md
• Split infrastructure.md into 5 focused sub-pages: Docker Services, Production Architecture, Video Pipeline, Federation, Storage
• Improved prose, introductions, and admonitions on all architecture pages
• Dark/light mode compatibility for all visual elements

Out of Scope

• Getting Started pages (docs/getting-started/overview.md, wizard-setup.md, cli-setup.md) — no changes
• Homepage (src/pages/index.tsx) — no changes
• New React components or MDX plugins
• Content changes to non-architecture pages
• Adding new diagrams beyond what exists

Context for Implementer

Write for an implementer who has never seen the codebase.

• Docusaurus version: 3.9.2 with @docusaurus/theme-mermaid plugin

• Mermaid config location: docusaurus.config.ts lines 122-133, under themeConfig.mermaid

• CSS location: src/css/custom.css — contains the Vidra design system (variables, dark mode, tables, focus indicators)

• Sidebar: Auto-generated from filesystem via sidebars.ts:17 — uses sidebar_position frontmatter for ordering

• Current architecture docs: docs/architecture/overview.md (3 diagrams) and docs/architecture/infrastructure.md (5 diagrams)

• Design system skill: .claude/skills/vidra-docs-design-theme/skill.md contains the full Vidra color palette, chart colors, and accessibility requirements. Consult this for all color decisions.

• Patterns to follow:

  • Frontmatter: sidebar_position + title (see docs/getting-started/overview.md:1-4)
  • Admonitions: :::tip, :::caution, :::info (used in wizard-setup.md:176-178)
  • Tables with headers (used extensively in current docs)

• Conventions:

  • Page titles use # heading matching the title frontmatter
  • Diagrams use Mermaid code blocks (```mermaid)
  • No MDX — all pages are plain .md

• Gotchas:

  • Mermaid themeVariables in docusaurus.config.ts apply globally to whichever base theme is active — they don't differentiate between light/dark mode. The theme: {light: 'base', dark: 'dark'} config handles the base theme switching.
  • Mermaid style SubgraphName fill:#color is the ONLY way to color subgraph backgrounds. Without it, subgraphs use the theme's auto-determined colors. This is acceptable and preferred for dark mode compatibility.
  • The base Mermaid theme uses primaryColor, secondaryColor, tertiaryColor to auto-generate node colors and subgraph backgrounds. The dark theme has its own built-in dark palette.
  • CSS targeting Mermaid SVGs works because Mermaid renders inline SVG in the DOM.

• Domain context: Vidra is a PeerTube-compatible video platform built in Go. The infrastructure docs describe its Docker services, production deployment, video processing pipeline, federation (ActivityPub/AT Protocol), and storage architecture.

Runtime Environment

• Start command: npm start (port 3000)
• Build command: npm run build
• Serve built site: npm run serve
• Note: Project switched from Yarn to npm (commit 9541a88). Use npm for all commands despite packageManager field in package.json.

Assumptions

• Mermaid diagrams without inline style will use the base theme's auto-coloring in light mode and the dark theme's built-in palette in dark mode — supported by Mermaid docs and docusaurus.config.ts:122-123. All tasks depend on this.
• The existing @docusaurus/theme-mermaid plugin handles theme switching automatically when the user toggles dark/light mode — supported by docusaurus.config.ts:30. Tasks 1-5 depend on this.
• Auto-generated sidebar from sidebars.ts:17 will correctly order new pages using sidebar_position frontmatter — supported by existing pages using this pattern. Tasks 3-5 depend on this.

Risks and Mitigations

Risk	Likelihood	Impact	Mitigation
Mermaid dark theme produces unreadable text	Medium	High	Add CSS fallback rules that force text colors in .mermaid elements for dark mode: [data-theme='dark'] .mermaid text { fill: #e8e8ec; }
Subgraphs lose visual differentiation without inline styles	Medium	Low	Acceptable trade-off — uniform theme colors are cleaner. If needed, can add back style with CSS-variable-friendly colors in a future iteration
Broken cross-references after page split	Low	Medium	Use relative links only within the architecture section. Verify all links in build output (Docusaurus throws on broken links via onBrokenLinks: 'throw' in config)

Goal Verification

Truths

1. All 8 Mermaid diagrams render correctly in both light and dark mode without hardcoded pastel fills
2. The infrastructure content is split across 5 separate sub-pages, each navigable from the sidebar
3. Every architecture page has introductory prose before its first diagram
4. The npm run build command completes without errors or broken link warnings
5. Dark mode diagrams have readable text (not washed-out or invisible)

Artifacts

1. docusaurus.config.ts — Updated mermaid themeVariables
2. src/css/custom.css — New Mermaid CSS rules for dark/light mode
3. docs/architecture/overview.md — Redesigned with 3 updated diagrams
4. docs/architecture/docker-services.md — New page
5. docs/architecture/production-architecture.md — New page
6. docs/architecture/video-pipeline.md — New page
7. docs/architecture/federation.md — New page
8. docs/architecture/storage.md — New page
9. docs/architecture/infrastructure.md — Converted to hub page or removed

Progress Tracking

• Task 1: Mermaid theme configuration + custom CSS
• Task 2: Redesign architecture overview diagrams
• Task 3: Create Docker Services sub-page
• Task 4: Create Production Architecture sub-page
• Task 5: Create Video Pipeline sub-page
• Task 6: Create Federation sub-page
• Task 7: Create Storage sub-page
• Task 8: Convert infrastructure.md to hub page
• Task 9: Build verification and visual check Total Tasks: 9 | Completed: 9 | Remaining: 0

Implementation Tasks

Task 1: Mermaid Theme Configuration + Custom CSS

Objective: Update the global Mermaid theme for better dark mode support and add CSS rules that improve diagram readability across both color modes.

Dependencies: None

Files:

• Modify: docusaurus.config.ts (lines 122-133, mermaid config)
• Modify: src/css/custom.css (add new Mermaid section)

Key Decisions / Notes:

• Update themeVariables to use Vidra brand colors that work with the base theme:
  • primaryColor: '#ccf3f5' (ice blue — keep as-is, works well)
  • primaryTextColor: '#0c2035' (deep navy — keep as-is)
  • primaryBorderColor: '#0979A5' (brand primary — keep as-is)
  • lineColor: '#1d4669' (steel blue — keep as-is)
  • secondaryColor: '#e8f4f8' (keep as-is)
  • tertiaryColor: '#f8fbfc' (keep as-is)
  • Add: noteBkgColor: '#f8fbfc', noteTextColor: '#0c2035', noteBorderColor: '#0979A5' for sequence diagram notes
  • Add: actorTextColor: '#0c2035', actorBorder: '#0979A5', actorBkg: '#ccf3f5' for sequence diagram actors
  • Add: signalColor: '#1d4669', signalTextColor: '#0c2035' for sequence diagram signals
• Add CSS section /* Mermaid Diagrams */ to custom.css with:
  • Dark mode text color overrides: [data-theme='dark'] .docusaurus-mermaid-container text { ... }
  • Font size improvement for readability
  • Sequence diagram participant box styling
  • Ensure .edgeLabel text is readable in both modes

Definition of Done:

• Mermaid themeVariables include sequence diagram actor/note colors
• CSS contains dark mode overrides for Mermaid text elements
• CSS contains dark mode overrides for Mermaid node backgrounds (.node rect, .node circle, .cluster rect) if the light themeVariables produce jarring colors on the dark canvas
• No diagnostics errors
• npm run build passes

Verify:

npm run build 2>&1 | tail -5

---

Task 2: Redesign Architecture Overview Diagrams

Objective: Update all 3 diagrams in overview.md to remove hardcoded inline style directives and add introductory prose for each diagram section.

Dependencies: Task 1

Files:

• Modify: docs/architecture/overview.md

Key Decisions / Notes:

• High-Level Architecture diagram (line 13-71): Remove style Core fill:#e8f5e9, style Application fill:#e3f2fd, style External fill:#fff3e0. The Mermaid base theme will auto-color subgraphs using primaryColor/secondaryColor/tertiaryColor from the global config. Add a 1-2 sentence intro before the diagram explaining what the reader should focus on.
• Request Flow diagram (line 75-102): This is a sequence diagram — no inline styles to remove. Add a brief intro explaining the cache-hit/miss flow.
• Clean Architecture Layers diagram (line 106-135): Remove style Core fill:#e8f5e9, style Application fill:#e3f2fd, style External fill:#fff3e0. Add an intro connecting the diagram to the layer responsibilities table below it.
• Add a brief page-level introduction under the # Architecture Overview heading (currently just one sentence at line 8).

Definition of Done:

• No style directives remain in any diagram in overview.md
• Each diagram section has 1-2 sentences of introductory text
• Page has an expanded introduction paragraph
• npm run build passes

Verify:

grep -c "style.*fill:" docs/architecture/overview.md  # Should be 0
npm run build 2>&1 | tail -5

---

Task 3: Create Docker Services Sub-Page

Objective: Extract the Docker Compose Services section from infrastructure.md into a new focused page with improved content and a redesigned diagram.

Dependencies: Task 1

Files:

• Create: docs/architecture/docker-services.md

Key Decisions / Notes:

• Pre-flight: Verify no other docs under docs/architecture/ already use sidebar_position values 3-7: grep -r 'sidebar_position' docs/architecture/
• Set sidebar_position: 3 (after infrastructure hub page at position 2)
• Extract content from infrastructure.md lines 10-42 (Docker Compose Services diagram)
• Also extract the Development Network Ports table (lines 231-244) — it logically belongs with Docker services
• Remove all inline style from the diagram (lines 40-41: style Core fill:#e3f2fd, style Optional fill:#f3e5f5)
• Add an introduction explaining what Docker Compose services are provided and when to use them
• Add a :::tip admonition about the Docker Compose profiles (reference from cli-setup.md lines 183-197)
• Add a brief description for each service in the diagram (not just port numbers)

Definition of Done:

• New page renders in sidebar under Architecture
• Diagram has no inline style directives
• Page has introductory prose explaining the Docker services
• Development ports table is included
• npm run build passes

Verify:

grep -c "style.*fill:" docs/architecture/docker-services.md  # Should be 0
npm run build 2>&1 | tail -5

---

Task 4: Create Production Architecture Sub-Page

Objective: Extract the Production Architecture and Deployment Options sections from infrastructure.md into a new focused page.

Dependencies: Task 1

Files:

• Create: docs/architecture/production-architecture.md

Key Decisions / Notes:

• Set sidebar_position: 4
• Extract content from infrastructure.md lines 44-101 (Production Architecture diagram) and lines 261-296 (Deployment Options, K8s, Recommended Production Setup)
• Remove all inline style from the diagram (lines 96-100: style CDN fill:#fff3e0, style App fill:#e3f2fd, etc.)
• Add an introduction explaining the multi-tier production architecture
• Add :::info admonitions for scaling recommendations
• The Recommended Production Setup table (lines 288-296) provides good context — keep it and expand with brief descriptions

Definition of Done:

• New page renders in sidebar under Architecture
• Diagram has no inline style directives
• Page has introductory prose and deployment guidance
• Includes Kubernetes manifest listing and recommended setup table
• npm run build passes

Verify:

grep -c "style.*fill:" docs/architecture/production-architecture.md  # Should be 0
npm run build 2>&1 | tail -5

---

Task 5: Create Video Pipeline Sub-Page

Objective: Extract the Video Upload & Processing Pipeline section from infrastructure.md into a new focused page with expanded explanations.

Dependencies: Task 1

Files:

• Create: docs/architecture/video-pipeline.md

Key Decisions / Notes:

• Set sidebar_position: 5
• Extract content from infrastructure.md lines 103-139 (Video Upload & Processing Pipeline sequence diagram)
• This is a sequence diagram — no inline style to remove, but the global theme improvements from Task 1 will apply
• Add introductory prose explaining the upload flow, why chunked upload is used, and what happens during transcoding
• Add a :::info admonition about the transcoding resolutions (240p through 1080p)
• Consider adding a brief text summary of the pipeline stages below the diagram for users who prefer reading to diagrams

Definition of Done:

• New page renders in sidebar under Architecture
• Page has introductory prose explaining the pipeline
• Sequence diagram renders correctly
• Includes text summary of pipeline stages
• npm run build passes

Verify:

npm run build 2>&1 | tail -5

---

Task 6: Create Federation Sub-Page

Objective: Extract the Federation Architecture section from infrastructure.md into a new focused page with the protocols table and expanded explanations.

Dependencies: Task 1

Files:

• Create: docs/architecture/federation.md

Key Decisions / Notes:

• Set sidebar_position: 6
• Extract content from infrastructure.md lines 141-184 (Federation Architecture diagram + Federation Protocols table)
• Remove all inline style from the diagram (lines 171-174: style Instance_A fill:#e3f2fd, etc.)
• Add introductory prose explaining what federation means for Vidra — connecting to the broader Fediverse
• Add brief explanations for each protocol in the table (beyond just "Purpose" and "Compatibility")
• Add a :::tip admonition about PeerTube compatibility

Definition of Done:

• New page renders in sidebar under Architecture
• Diagram has no inline style directives
• Page has introductory prose about federation
• Protocols table is included with descriptions
• npm run build passes

Verify:

grep -c "style.*fill:" docs/architecture/federation.md  # Should be 0
npm run build 2>&1 | tail -5

---

Task 7: Create Storage Sub-Page

Objective: Extract the Storage Architecture section from infrastructure.md into a new focused page, including integration test ports.

Dependencies: Task 1

Files:

• Create: docs/architecture/storage.md

Key Decisions / Notes:

• Set sidebar_position: 7
• Extract content from infrastructure.md lines 186-227 (Storage Architecture diagram) and lines 246-259 (Integration Testing ports)
• Remove all inline style from the diagram (lines 223-226: style Upload fill:#fff3e0, etc.)
• Add introductory prose explaining the three storage tiers (primary, distributed, serving)
• Add explanations for when to use each storage backend (local vs S3 vs IPFS)
• The integration test ports table logically fits here as it covers test infrastructure

Definition of Done:

• New page renders in sidebar under Architecture
• Diagram has no inline style directives
• Page has introductory prose about storage tiers
• Integration test ports table is included
• npm run build passes

Verify:

grep -c "style.*fill:" docs/architecture/storage.md  # Should be 0
npm run build 2>&1 | tail -5

---

Task 8: Convert infrastructure.md to Hub Page

Objective: Replace the monolithic infrastructure page with a lightweight hub that links to the focused sub-pages.

Dependencies: Tasks 3, 4, 5, 6, 7

Files:

• Modify: docs/architecture/infrastructure.md

Key Decisions / Notes:

• Before making changes, audit all cross-references to this page:

  grep -r 'architecture/infrastructure' docs/ src/ docusaurus.config.ts

  Update any hardcoded links found in TSX, config, or other docs to point to the correct sub-page. onBrokenLinks: 'throw' only catches markdown-to-markdown links, not TSX or external references.
• Keep sidebar_position: 2 and title: Infrastructure
• Replace all content with:
  • A brief 2-3 sentence introduction about Vidra's infrastructure
  • A card-style list linking to each sub-page with a one-line description:
    • Docker Services — Development environment and Docker Compose services
    • Production Architecture — Multi-tier production deployment and scaling
    • Video Pipeline — Upload, transcoding, and distribution workflow
    • Federation — ActivityPub, AT Protocol, and cross-instance communication
    • Storage — Local, S3, IPFS storage and serving architecture
• Use standard Markdown links (not custom components) to keep it simple

Definition of Done:

• infrastructure.md is a clean hub page with links to all 5 sub-pages
• All links resolve correctly
• No diagram content remains on this page
• npm run build passes

Verify:

npm run build 2>&1 | tail -5

---

Task 9: Build Verification and Visual Check

Objective: Verify the complete site builds without errors and all diagrams render correctly.

Dependencies: Tasks 1-8

Files:

• No file changes — verification only

Key Decisions / Notes:

• Run npm run build to verify no broken links or build errors
• Start dev server with yarn start and use playwright-cli to visually verify
• Use session isolation: PW_SESSION="${PILOT_SESSION_ID:-default}"
• Check each architecture page renders diagrams in light mode
• Toggle dark mode and verify diagrams remain readable
• Check sidebar shows correct hierarchy and ordering
• Verify no page contains hardcoded style.*fill: in Mermaid blocks

Playwright-cli verification commands:

PW_SESSION="${PILOT_SESSION_ID:-default}"
playwright-cli -s="$PW_SESSION" open http://localhost:3000/docs/architecture/overview
playwright-cli -s="$PW_SESSION" snapshot
playwright-cli -s="$PW_SESSION" screenshot --filename=light-mode
# Click the actual Docusaurus color mode toggle (in navbar) to trigger real Mermaid theme re-render
playwright-cli -s="$PW_SESSION" snapshot  # Find the toggle button ref
playwright-cli -s="$PW_SESSION" click <toggle-ref>  # Click the actual toggle, not eval setAttribute
playwright-cli -s="$PW_SESSION" snapshot
playwright-cli -s="$PW_SESSION" screenshot --filename=dark-mode
# Repeat for each sub-page
playwright-cli -s="$PW_SESSION" close

Important: Do NOT use eval "document.documentElement.setAttribute('data-theme', 'dark')" — this bypasses Docusaurus's React-driven color mode switching and the Mermaid theme re-render won't fire. Always click the actual navbar toggle.

Definition of Done:

• npm run build exits 0 with no warnings about broken links
• All architecture pages render diagrams in light mode (verified via playwright-cli)
• All diagrams are readable in dark mode (verified via playwright-cli dark mode toggle)
• Sidebar navigation works correctly across all sub-pages
• grep -r "style.*fill:" docs/architecture/*.md returns no matches

Verify:

npm run build
grep -r "style.*fill:" docs/architecture/*.md  # Should return nothing

Open Questions

None — all design decisions resolved.

Deferred Ideas

• Add interactive Mermaid diagram zoom/pan for complex diagrams (requires custom component)
• Add a "system requirements calculator" based on selected services
• Create animated sequence diagrams for the video pipeline
• Add Mermaid classDef styling once a per-theme approach is available in Docusaurus