Rework Architecture Images

[darenegade]

We got multiple images that almost look identically, e.g. docs/architecture/assets/Anwendung_zentraleGUI_PermissionService.png. What purpose does Identity Provider have here? Its just floating around. ;)

Originally posted by @devtobi in #940 (comment)

Problems

• https://refarch.oss.muenchen.de/architecture/frontend-architecture.html#centralized-frontend : Frontend part of gateway instead of current default separate service
• Images with no background and black text not readable in darkmode
  • https://refarch.oss.muenchen.de/architecture/external-access.html
  • https://refarch.oss.muenchen.de/architecture/security-flows.html

[darenegade]

@coderabbitai plan

[coderabbitai]

Warning

A plan generation is already in progress. Please wait for it to complete before requesting a new plan.

[coderabbitai]

Coding Plan

Summary

• Consolidate the multiple near-identical architecture PNGs into a single canonical diagram, preferably converted to inline Mermaid to match the site's existing convention and eliminate binary duplication.
• Fix the orphaned "Identity Provider" node by connecting it to both the API Gateway and Backend (per the develop.md precedent), or omitting it where authentication isn't the diagram's concern.
• Reconcile "PermissionService" as a Backend↔Keycloak/UMA capability rather than a disconnected standalone box, aligning with security.md.
• Update all documentation references, wire any new page into the VitePress nav/sidebar, and ensure lint/build gates pass.

Design Choices

Design Choice 1: Should the reworked architecture diagrams remain as PNG image assets or be converted to inline Mermaid diagrams?

Options Considered:

1. Keep PNG images — re-export corrected/consolidated PNGs from whatever external tool authored them; fastest if the source diagram files are available.
2. Convert to inline Mermaid — replace the PNGs with Mermaid diagrams embedded in Markdown, matching every other diagram on the site and eliminating binary duplication.

Chosen Option: 2

Rationale: Converting to Mermaid directly fixes the "multiple near-identical images" root cause (duplication becomes reusable/diffable text), matches the site's established convention, and makes the Identity Provider connections trivially editable — Option 1 is only preferable if the diagrams must remain images for an external constraint, in which case Phase 1's consolidation guidance still applies. The ticket complains about multiple near-identical images, which is a classic symptom of hard-to-maintain binary diagram assets. The rest of the site uses Mermaid exclusively.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Audit and Consolidate the Duplicate Diagrams

Establish the full set of near-identical architecture images and collapse them into a single, maintainable source of truth. This phase focuses on removing the redundancy the reviewer flagged.

Task 1: Catalog the architecture images and identify the shared template

Enumerate every asset under docs/architecture/assets/ (on the PR #940 branch) and determine what varies between them.

• Operate against the PR #940 branch where docs/architecture/ and its assets/ PNGs exist (they are absent from this snapshot).
• List all Anwendung_* / architecture PNGs, and record for each what differs (component name, integration variant, presence/absence of the Identity Provider node).
• Confirm whether the images are genuine duplicates differing only by one component label — the likely case given the Anwendung_zentraleGUI_PermissionService.png naming.
• Identify where each image is referenced from within any docs/architecture/*.md page so references can be updated later.

Task 2: Define a single consolidated diagram (or minimal set)

Replace the redundant variants with one canonical diagram, converted to inline Mermaid per the site convention.

• Author a single Mermaid diagram (flowchart) that captures the shared architecture, following the pattern already used in docs/overview.md and docs/cross-cutting-concepts/security.md.
• Only retain multiple diagrams if they convey genuinely distinct information; collapse purely cosmetic variants into one.
• Mirror the %% Authentication / %% Main application flow grouping style established in docs/templates/develop.md so auth relationships are visually separated but connected.

🤖 Prompt for AI agents

Implement Phase 1: audit and consolidate the near-duplicate architecture
diagrams to remove redundancy.

- Operate against the PR `#940` branch context where `docs/architecture/` and its
`assets/*.png` files exist (they are not in this snapshot).
- Enumerate every `Anwendung_*` / architecture PNG under
`docs/architecture/assets/`, recording for each what differs (component name,
integration variant, presence/absence of the Identity Provider node).
- Confirm whether the images are genuine duplicates differing only by one
component label, given the `Anwendung_zentraleGUI_PermissionService.png` naming
pattern.
- Identify every `docs/architecture/*.md` page referencing each image so
references can be updated later.
- Author a single consolidated Mermaid `flowchart` diagram capturing the shared
architecture, following the pattern already used in `docs/overview.md` and
`docs/cross-cutting-concepts/security.md`.
- Only keep multiple diagrams if they convey genuinely distinct information;
collapse purely cosmetic variants into one canonical diagram.
- Mirror the `%% Authentication` / `%% Main application flow` grouping style
established in `docs/templates/develop.md` so authentication relationships are
visually separated but connected.

Phase 2: Correct the Identity Provider and PermissionService Semantics

Address the reviewer's core question by ensuring the Identity Provider is properly connected and that terminology matches the existing documentation model.

Task 1: Wire the Identity Provider into the diagram (or remove it)

Eliminate the "floating" IDP node by connecting it consistently with the only established precedent, or drop it if it adds no meaning to the specific diagram.

• Follow the docs/templates/develop.md convention: the Identity Provider (SSO/Keycloak) connects to both the API Gateway (login/session) and the Backend (JWT validation / permission lookups).
• If a particular consolidated diagram does not concern authentication, omit the IDP entirely rather than leaving it unconnected — consistent with overview.md/security.md, which deliberately omit it.
• Ensure the IDP label/terminology is consistent with the docs (the docs use "SSO"/"Keycloak"; reconcile "Identity Provider" wording so it is not a new, ungrounded term).

Task 2: Reconcile the "PermissionService" concept

Align the diagram with the documented reality that permission resolution is a Keycloak/UMA capability, not a standalone service floating next to the IDP.

• Per docs/cross-cutting-concepts/security.md, model permission resolution as a Backend → Identity Provider (Keycloak/UMA) interaction rather than a separate disconnected "PermissionService" box.
• If a distinct permission concept must be shown, attach it to the Backend/IDP relationship so it is not orphaned, and label it in line with the "Keycloak permissions"/UMA terminology already used in the docs.

🤖 Prompt for AI agents

Implement Phase 2: fix the semantically orphaned Identity Provider node and
reconcile the PermissionService concept with documented terminology.

- Wire the Identity Provider (SSO/Keycloak) into the consolidated diagram
following the `docs/templates/develop.md` convention: connect it to both the API
Gateway (login/session) and the Backend (JWT validation / permission lookups).
- If a particular consolidated diagram does not concern authentication, omit the
IDP entirely rather than leaving it unconnected, consistent with how
`overview.md`/`security.md` deliberately omit it.
- Reconcile the IDP label/terminology with existing docs usage of
"SSO"/"Keycloak" so "Identity Provider" is not left as a new, ungrounded term.
- Remove or reconcile the standalone "PermissionService" box: per
`docs/cross-cutting-concepts/security.md`, model permission resolution as a
Backend → Identity Provider (Keycloak/UMA) interaction rather than a separate
disconnected component.
- If a distinct permission concept must still be shown, attach it directly to
the Backend/IDP relationship (not orphaned) and label it using the "Keycloak
permissions"/UMA terminology already used in the docs.

Phase 3: Integrate into the VitePress Site and Pass Quality Gates

Ensure the reworked diagram is discoverable, references are updated, and the site builds cleanly.

Task 1: Update references and remove obsolete assets

Point all documentation at the consolidated diagram and delete the now-redundant image files.

• Update any docs/architecture/*.md pages that referenced the removed PNGs to embed the new Mermaid diagram (or the retained image).
• Delete the redundant PNG assets from docs/architecture/assets/ once no longer referenced.
• If a new architecture page is introduced, add a matching entry to both the nav and sidebar arrays in docs/.vitepress/config.mts.

Task 2: Validate build and linting

Confirm the reworked docs meet the site's quality gates.

• Run npm run lint (markdownlint + Prettier) and npm run fix as needed; must be error-free before committing.
• Run npm run build / npm run dev to confirm the Mermaid diagram renders and no broken image/nav links remain.

🤖 Prompt for AI agents

Implement Phase 3: integrate the consolidated diagram into the VitePress site
and ensure quality gates pass.

- Update every `docs/architecture/*.md` page that referenced the removed PNGs so
it embeds the new consolidated Mermaid diagram (or the retained image instead).
- Delete the now-redundant PNG assets from `docs/architecture/assets/` once no
longer referenced by any page (including
`Anwendung_zentraleGUI_PermissionService.png` and other near-duplicates
identified in Phase 1).
- If a new architecture page is introduced as part of this rework, add a
matching entry to both the `nav` and `sidebar` arrays in
`docs/.vitepress/config.mts`.
- Run `npm run lint` (markdownlint + Prettier) and `npm run fix` as needed; this
must be error-free before committing.
- Run `npm run build` / `npm run dev` to confirm the Mermaid diagram renders
correctly and that there are no broken image or navigation links remaining.

Research

The documentation lives in a VitePress site under docs/, which standardizes on inline Mermaid diagrams (via vitepress-plugin-mermaid) rather than static images — no PNG-based architecture diagrams exist in the current tree. Authentication is treated as a cross-cutting concern centered on an external SSO/Identity Provider (Keycloak); ADR-002 defines the IDP as an out-of-scope infrastructure dependency, and security.md establishes that permission resolution is a Keycloak/UMA capability queried by the Backend (there is no standalone "PermissionService"). The only existing precedent for drawing an IDP node (docs/templates/develop.md) connects it to both the API Gateway and the Backend under a dedicated %% Authentication grouping. Pages are wired into nav and sidebar in docs/.vitepress/config.mts, and changes must pass markdownlint + Prettier.

Important: the specific docs/architecture/assets/*.png files referenced by the ticket are not present in this snapshot (shallow clone; they belong to the PR #940 branch). The implementing agent must operate against the branch/context where those assets exist.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement Phase 1: audit and consolidate the near-duplicate architecture
diagrams to remove redundancy.

- Operate against the PR `#940` branch context where `docs/architecture/` and its
`assets/*.png` files exist (they are not in this snapshot).
- Enumerate every `Anwendung_*` / architecture PNG under
`docs/architecture/assets/`, recording for each what differs (component name,
integration variant, presence/absence of the Identity Provider node).
- Confirm whether the images are genuine duplicates differing only by one
component label, given the `Anwendung_zentraleGUI_PermissionService.png` naming
pattern.
- Identify every `docs/architecture/*.md` page referencing each image so
references can be updated later.
- Author a single consolidated Mermaid `flowchart` diagram capturing the shared
architecture, following the pattern already used in `docs/overview.md` and
`docs/cross-cutting-concepts/security.md`.
- Only keep multiple diagrams if they convey genuinely distinct information;
collapse purely cosmetic variants into one canonical diagram.
- Mirror the `%% Authentication` / `%% Main application flow` grouping style
established in `docs/templates/develop.md` so authentication relationships are
visually separated but connected.
===============================================================================

Task: 2

Implement Phase 2: fix the semantically orphaned Identity Provider node and
reconcile the PermissionService concept with documented terminology.

- Wire the Identity Provider (SSO/Keycloak) into the consolidated diagram
following the `docs/templates/develop.md` convention: connect it to both the API
Gateway (login/session) and the Backend (JWT validation / permission lookups).
- If a particular consolidated diagram does not concern authentication, omit the
IDP entirely rather than leaving it unconnected, consistent with how
`overview.md`/`security.md` deliberately omit it.
- Reconcile the IDP label/terminology with existing docs usage of
"SSO"/"Keycloak" so "Identity Provider" is not left as a new, ungrounded term.
- Remove or reconcile the standalone "PermissionService" box: per
`docs/cross-cutting-concepts/security.md`, model permission resolution as a
Backend → Identity Provider (Keycloak/UMA) interaction rather than a separate
disconnected component.
- If a distinct permission concept must still be shown, attach it directly to
the Backend/IDP relationship (not orphaned) and label it using the "Keycloak
permissions"/UMA terminology already used in the docs.
===============================================================================

Task: 3

Implement Phase 3: integrate the consolidated diagram into the VitePress site
and ensure quality gates pass.

- Update every `docs/architecture/*.md` page that referenced the removed PNGs so
it embeds the new consolidated Mermaid diagram (or the retained image instead).
- Delete the now-redundant PNG assets from `docs/architecture/assets/` once no
longer referenced by any page (including
`Anwendung_zentraleGUI_PermissionService.png` and other near-duplicates
identified in Phase 1).
- If a new architecture page is introduced as part of this rework, add a
matching entry to both the `nav` and `sidebar` arrays in
`docs/.vitepress/config.mts`.
- Run `npm run lint` (markdownlint + Prettier) and `npm run fix` as needed; this
must be error-free before committing.
- Run `npm run build` / `npm run dev` to confirm the Mermaid diagram renders
correctly and that there are no broken image or navigation links remaining.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!