mocode-software/meldestelle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
897394e27e
meldestelle/docs/01_Architecture/adr/0024-plug-and-play-architektur.md
StefanMoCoAt 5887ac7b6c
Some checks failed
Desktop CI — Headless Tests & Build / Compose Desktop — Tests (headless) & Build (push) Has been cancelled
Details
Build and Publish Docker Images / build-and-push (., backend/infrastructure/gateway/Dockerfile, api-gateway, api-gateway) (push) Has been cancelled
Details
Build and Publish Docker Images / build-and-push (., backend/services/ping/Dockerfile, ping-service, ping-service) (push) Has been cancelled
Details
Build and Publish Docker Images / build-and-push (., config/docker/caddy/web-app/Dockerfile, web-app, web-app) (push) Has been cancelled
Details
Build and Publish Docker Images / build-and-push (., config/docker/keycloak/Dockerfile, keycloak, keycloak) (push) Has been cancelled
Details
chore: update roadmap with finalized frontend modernization phase, refactor turnier and veranstalter features to adhere to Plug-and-Play architecture, and improve code hygiene in core frontend modules
2026-04-20 10:55:28 +02:00

2.5 KiB
Raw Blame History

ADR-0024: Plug-and-Play Komponenten-Architektur für Multiplattform-Stabilität

Status

Akzeptiert

Kontext

Das Projekt "Meldestelle" strebt eine Multiplattform-Anwendung (KMP) für Desktop, Web und Mobile an. Jüngste Stabilitätsprobleme im Frontend (der "Kartenhaus-Effekt") wurden durch eng gekoppelte UI-Komponenten und Screens verursacht. Änderungen in einem Bereich (z.B. Routing) führten zu Zusammenbrüchen in nicht verwandten Features.

Besonders kritisch waren direkte Zugriffe auf Shell-interne Datenstrukturen via Reflection oder direkte Injektion von ViewModels innerhalb von Composables via koinInject(), was die Unabhängigkeit der Feature-Module untergrub.

Entscheidung

Wir führen eine "Plug-and-Play"-Architektur für alle Frontend-Komponenten ein. Diese Strategie stellt sicher, dass Komponenten in sich geschlossen, wiederverwendbar und unabhängig von ihrer Platzierung in der UI-Hierarchie sind.

1. Atomic Design Ebenen

  • Atome/Moleküle (core:design-system): Zustandlose, rein visuelle Elemente (z.B. MsButton, MsCard).
  • Plug-and-Play Organismen (features:* oder core:auth): Fachlich orientierte Komponenten (z.B. AuthStatusCard, PingActionGroup). Sie MÜSSEN ein ViewModel-Interface oder ein UI-State-Objekt verwenden.
  • Templates/Screens: Layout-orientierte Kompositionen von Organismen. Keine direkte Logik-Implementierung.

2. Striktes State Hoisting

  • Komponenten erhalten ihren Zustand über ein ViewModel oder ein State-Objekt, das als Parameter übergeben wird.
  • Sie geben Ereignisse über Lambdas zurück (z.B. onLoginClick: () -> Unit).
  • Sie dürfen NICHT direkt innerhalb des Composables auf globale Singletons oder Koin zugreifen.

3. Modulare Granularität

  • Features werden in kleine, testbare Einheiten zerlegt (z.B. PingConsole, PingControls).
  • Komponenten befinden sich in commonMain, um die Multiplattform-Verfügbarkeit sicherzustellen.

Konsequenzen

  • Positiv: Erhöhte Stabilität, höhere Wiederverwendbarkeit über Plattformen hinweg, einfacheres Testing, schnellere UI-Experimente.
  • Negativ: Geringfügiger Overhead bei der Definition von Interfaces und State-Objekten für kleine Komponenten.
  • Risiko: Over-Engineering einfacher Views. (Gegenmaßnahme: "Gesunder Menschenverstand" bei trivialen 1-Zeilen-Labels).

Einhaltung

  • Jede neue Feature-Implementierung MUSS gegen dieses ADR geprüft werden.
  • Bestehende Screens SOLLTEN im Zuge der Wartung in dieses Muster refactored werden.