Kuadrant / Kuadrant/architecture

Convert architectural overview diagrams from JPG images to mermaid

Open
#173 0 comments 0 reactions 0 assignees View on GitHub
documentation
Dominant language
No language data
Stars
3
Forks
16
Avg merge
7d 11h
Merged PRs (30d)
2

Description

## Summary

The [architectural overview page](https://docs.kuadrant.io/dev/architecture/docs/design/architectural-overview-v1/) 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](https://docs.kuadrant.io/dev/kuadrant-operator/doc/user-guides/egress/credential-injection/))
- 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

Contributor guide

Open the contributing guide

Research direction

Start with the architectural overview page and compare its seven listed JPG files: highest-level.jpg, control-plane-overview.jpg, data-plane-overview.jpg, single-cluster-layout.jpg, multi-cluster-layout.jpg, arch_observability_1.jpg, and arch_observability_2.jpg. Review the existing Mermaid usage referenced in the issue, then run `mkdocs serve -s` to verify the converted page and confirm no image references remain.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.