Stefan Mogeritsch
bf8facfa66
Added documentation to outline the Offline-First strategy for the KMP frontend, emphasizing the use of SQLDelight with cross-platform storage. Also included guidance for setting up Web targets, covering OPFS integration and Web Worker usage. Updated ADRs with decisions for SQLDelight and Koin adoption.
95 lines
5.0 KiB
Markdown
95 lines
5.0 KiB
Markdown
# Repository-Architektur (MP-22)
|
||
|
||
**WARNUNG (Januar 2026): Dieses Dokument ist veraltet.** Die hier beschriebene "Soll"-Struktur wurde teilweise umgesetzt, aber wichtige strategische Änderungen sind in den Statusberichten vom Januar 2026 dokumentiert. Dieses Dokument dient nur noch als historischer Referenzpunkt.
|
||
|
||
**Aktuelle Informationen finden Sie in:**
|
||
* `docs/90_Reports/Backend_Status_Report_01-2026.md`
|
||
* `docs/90_Reports/Frontend_Status_Report_01-2026.md`
|
||
* Den ADRs in `docs/01_Architecture/adr/`
|
||
|
||
---
|
||
|
||
## Zusammenfassung der wichtigsten Änderungen (Januar 2026)
|
||
|
||
* **Backend:** Ein Konflikt zwischen Spring Boot und Spring Cloud wurde durch einen Downgrade von Spring Cloud gelöst.
|
||
* **Frontend:** Die Persistenz-Strategie wurde von Room auf **SQLDelight** umgestellt, um echte Cross-Platform-Fähigkeit (insbesondere für Web/Wasm) zu ermöglichen.
|
||
* **Modul-Struktur:** Das `core:core-utils`-Modul wurde bereinigt, um eine strikte Trennung zwischen KMP-kompatiblem Code und JVM-spezifischem Code zu gewährleisten. JVM-spezifischer Code wurde in das neue Modul `:backend:infrastructure:persistence` verschoben.
|
||
* **Build-System:** Die `libs.versions.toml` wurde stark refaktoriert und nutzt nun Bundles zur Vereinfachung der Gradle-Dateien.
|
||
|
||
---
|
||
|
||
## Ursprünglicher Inhalt (Veraltet)
|
||
|
||
### Zielstruktur (Top-Level)
|
||
|
||
backend/ Gateway, Discovery (optional), Services
|
||
gateway Spring Cloud Gateway
|
||
discovery
|
||
services
|
||
frontend/ KMP Frontend
|
||
shells Ausführbare Apps (Assembler)
|
||
features Vertical Slices (kein Feature→Feature)
|
||
core Shared Foundation (Design-System, Network, Local-DB, Auth, Domain)
|
||
design-system
|
||
domain
|
||
network
|
||
local-db
|
||
navigation
|
||
docker/ Docker Compose, .env.example, Monitoring-/Core-Konfiguration
|
||
docs/ Architektur, ADRs, C4-Modelle, Guides
|
||
adr Architecture Decision Records (ADRs)
|
||
c4 C4-Diagramme (PlantUML Quellen)
|
||
|
||
### Ist → Soll Mapping (erste Tranche)
|
||
|
||
- Frontend
|
||
- clients/app → frontend/shells/meldestelle-portal (verschieben in Folge-Commit)
|
||
- clients/shared/common-ui → frontend/core/design-system (verschieben in Folge-Commit)
|
||
- clients/shared/navigation → frontend/core/navigation (verschieben in Folge-Commit)
|
||
|
||
- Backend
|
||
- infrastructure/gateway → backend/gateway (verschieben in Folge-Commit)
|
||
- services/* → backend/services/* (verschieben in Folge-Commit)
|
||
- Discovery (falls genutzt) → backend/discovery
|
||
|
||
- Docker
|
||
- compose.yaml → docker/docker-compose.yml (neu angelegt, Makefile angepasst)
|
||
- .env Handling → docker/.env.example (neu, als Template)
|
||
|
||
### Build/Gradle
|
||
|
||
- settings.gradle.kts bleibt vorerst unverändert. Modul-Verschiebungen folgen in einem separaten Schritt mit angepassten include-Pfaden.
|
||
- Version Catalog (gradle/libs.versions.toml) bleibt die einzige Quelle der Versionswahrheit.
|
||
|
||
### Richtlinien (Kurzfassung)
|
||
|
||
- Features kommunizieren ausschließlich über Routen (Navigation) und Shared-Modelle in frontend/core/domain.
|
||
- Kein manueller Authorization-Header – nur der DI-verwaltete apiClient aus frontend/core/network (Koin Named Binding).
|
||
- SQLDelight als Offline-SSoT: Schema/Migrationen zentral versionieren, UI liest stets lokal und synchronisiert im Hintergrund.
|
||
|
||
### DI-Policy & Architecture Guards (MP-23)
|
||
|
||
- DI-Policy (Frontend)
|
||
- Http‑Requests erfolgen ausschließlich über den via Koin bereitgestellten `apiClient` (named Binding) aus `:frontend:core:network`.
|
||
- Manuelles Setzen des `Authorization`‑Headers ist verboten. Token‑Handling wird zentral im `apiClient` konfiguriert (Auth‑Plugin/Interceptor).
|
||
- Basis‑URL wird plattformspezifisch aufgelöst:
|
||
- JVM/Desktop: Env `API_BASE_URL` (Fallback `http://localhost:8081`).
|
||
- Web/JS: `globalThis.API_BASE_URL` (z. B. per `index.html` oder Proxy), sonst `window.location.origin`, Fallback `http://localhost:8081`.
|
||
|
||
- Architecture Guards (Frontend‑Scope)
|
||
- Root‑Task `archGuards` bricht den Build ab, wenn verbotene Muster gefunden werden (manuelle `Authorization`‑Header). Tests sind ausgenommen; Backend ist ausgenommen.
|
||
- Statische Analyse verfügbar über `detekt` und `ktlintCheck`; Aggregator `staticAnalysis` führt alles zusammen.
|
||
|
||
- Hinweise für Features
|
||
- Features importieren keine anderen Features (Kommunikation über Navigation + Shared‑Domain‑Modelle). Eine explizite Detekt‑Regel folgt.
|
||
- Netzwerkzugriffe in Features nutzen Koin über die App‑Shell (DI‑Bootstrap). Für schrittweise Migration kann eine Factory den `apiClient` optional beziehen.
|
||
|
||
### Nächste Schritte (MP-22 Folgetasks)
|
||
|
||
1. Physisches Verschieben der Frontend-Module gemäß Mapping und Anpassung von settings.gradle.kts.
|
||
2. Physisches Verschieben der Backend-Komponenten in backend/* inkl. evtl. Package-Pfade, sofern notwendig.
|
||
3. Ergänzung von docker-compose.services.yml und docker-compose.clients.yml mit echten Overlays.
|
||
4. Erstellen der ersten ADRs unter `docs/01_Architecture/adr/` (Koin, SQLDelight, Optimistic Locking, Freshness UI, Core Domain).
|
||
|
||
Hinweis: ADRs liegen ab sofort zentral unter `docs/01_Architecture/adr/`. C4-Diagramme liegen unter `docs/01_Architecture/c4/`.
|