Skip to content

Convert architectural overview diagrams from JPG images to mermaid #173

Description

@jasonmadigan

Summary

The architectural overview page uses 7 embedded JPG images for its diagrams. These should be converted to mermaid format for maintainability and consistency.

Motivation

  • JPG diagrams go stale — they require image editing tools to update, so they tend to drift from reality
  • Mermaid diagrams are text-based and live in the markdown source, making them easy to update alongside code changes
  • Other docs pages already use mermaid successfully (e.g. the egress credential injection guide)
  • Mermaid renders natively in MkDocs Material and looks consistent with the rest of the site

Diagrams to convert

  1. Highest-level architecture (images/highest-level.jpg)
  2. Control plane overview (images/control-plane-overview.jpg)
  3. Data plane overview (images/data-plane-overview.jpg)
  4. Single cluster layout (images/single-cluster-layout.jpg)
  5. Multi-cluster layout (images/multi-cluster-layout.jpg)
  6. Single cluster observability (images/arch_observability_1.jpg)
  7. Multi-cluster observability (images/arch_observability_2.jpg)

Acceptance criteria

  • All 7 diagrams replaced with mermaid equivalents
  • Mermaid diagrams accurately represent the same information as the original images
  • Original JPG files removed from the repo
  • Page renders correctly with mkdocs serve -s

Reviewing a PR for this

  • Compare each mermaid diagram against the original JPG to verify accuracy
  • Check the rendered output with mkdocs serve -s on the architectural overview page
  • Verify no broken image references remain

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions