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
- Highest-level architecture (
images/highest-level.jpg)
- Control plane overview (
images/control-plane-overview.jpg)
- Data plane overview (
images/data-plane-overview.jpg)
- Single cluster layout (
images/single-cluster-layout.jpg)
- Multi-cluster layout (
images/multi-cluster-layout.jpg)
- Single cluster observability (
images/arch_observability_1.jpg)
- Multi-cluster observability (
images/arch_observability_2.jpg)
Acceptance criteria
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
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
Diagrams to convert
images/highest-level.jpg)images/control-plane-overview.jpg)images/data-plane-overview.jpg)images/single-cluster-layout.jpg)images/multi-cluster-layout.jpg)images/arch_observability_1.jpg)images/arch_observability_2.jpg)Acceptance criteria
mkdocs serve -sReviewing a PR for this
mkdocs serve -son the architectural overview page