Kuadrant / Kuadrant/architecture
Convert architectural overview diagrams from JPG images to mermaid
- 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
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