meldestelle/client/README-CLIENT.md

🖥️ Client-Architektur - Meldestelle

Überblick

Das Client-Modul stellt die vollständige Benutzeroberflächen-Lösung für das Meldestelle-System bereit und liefert eine konsistente Erfahrung auf mehreren Plattformen durch Kotlin Multiplatform- und Compose Multiplatform-Technologien.

Architektur-Highlights:

• 🌐 Plattformübergreifend - Eine einzige Codebasis für Desktop (JVM) und Web (JavaScript) Anwendungen
• 🏗️ Moderne MVVM - Umfassende Model-View-ViewModel-Architektur mit ordnungsgemäßer Zustandsverwaltung
• 🧪 Testabdeckung - Produktionsbereit mit umfassenden Tests über alle Module
• 🚀 Optimiert - Build- und Laufzeit-Optimierungen für Leistung und Entwicklererfahrung
• 📱 Progressive - Web-App mit vollständigen PWA-Fähigkeiten für mobile und Desktop-Installation

---

Client-Module Struktur

client/
├── common-ui/                          # Geteilte UI-Komponenten und Geschäftslogik
│   ├── src/commonMain/                 # Plattformübergreifende MVVM-Implementierung
│   ├── src/commonTest/                 # Umfassende Test-Suite (32 Tests)
│   └── README-CLIENT-COMMON-UI.md      # Detaillierte common-ui Dokumentation
├── desktop-app/                        # Native Desktop-Anwendung
│   ├── src/jvmMain/                    # Desktop-spezifische Implementierung
│   ├── src/jvmTest/                    # Desktop-Anwendungs-Tests
│   └── README-CLIENT-DESKTOP-APP.md    # Detaillierte desktop-app Dokumentation
├── web-app/                            # Progressive Web Application
│   ├── src/jsMain/                     # Web-spezifische Implementierung mit PWA
│   ├── src/jsTest/                     # JavaScript-kompatible Tests
│   └── README-CLIENT-WEB-APP.md        # Detaillierte web-app Dokumentation
└── README-CLIENT.md                    # Diese Übersichts-Dokumentation

---

Architektur-Überblick

Multi-Plattform-Strategie

Die Client-Architektur folgt einem geschichteten Ansatz mit maximaler Code-Wiederverwendung:

┌─────────────────────────────────────────────────┐
│                  Client-Apps                    │
├─────────────────┬───────────────────────────────┤
│  Desktop-App    │         Web-App               │
│  (JVM/Compose)  │    (Kotlin/JS + PWA)          │
├─────────────────┴───────────────────────────────┤
│              Common-UI Modul                    │
│         (Geteilte MVVM + Geschäftslogik)        │
├─────────────────────────────────────────────────┤
│    Plattformspezifische Abhängigkeiten          │
│   JVM: Ktor-CIO    │    JS: Ktor-JS             │
└─────────────────────────────────────────────────┘

MVVM-Implementierung

Die vollständige Client-Architektur implementiert das ordnungsgemäße MVVM-Muster:

• Model: Datenmodelle und Services (PingService, PingResponse)
• View: Compose UI-Komponenten (Desktop + Web)
• ViewModel: Zustandsverwaltung (PingViewModel, PingUiState)

Vier UI-Zustände Implementierung

Gemäß den trace-bullet-guideline.md Spezifikationen:

1. Initial-Zustand: PingUiState.Initial - Neutrale Nachricht, Button aktiv
2. Loading-Zustand: PingUiState.Loading - Ladeindikator, Button deaktiviert
3. Success-Zustand: PingUiState.Success - Positive Antwort, Button aktiv
4. Error-Zustand: PingUiState.Error - Klare Fehlernachricht, Button aktiv

---

Schnellstart

Voraussetzungen

Tool	Version	Zweck
JDK	21 (Temurin)	Desktop-Laufzeit und Build-System
Node.js	≥ 20	Web-Entwicklung und JavaScript-Laufzeit
Gradle	8.x (wrapper)	Build-Automatisierung (enthalten)

Entwicklungs-Befehle

# 🖥️ Desktop-Anwendung
./gradlew :client:desktop-app:run                    # Desktop-App starten
./gradlew :client:desktop-app:jvmTest               # Desktop-Tests ausführen

# 🌐 Web-Anwendung
./gradlew :client:web-app:jsBrowserDevelopmentRun   # Web-Dev-Server starten
./gradlew :client:web-app:jsTest                    # Web-Tests ausführen

# 🧩 Common-UI Modul
./gradlew :client:common-ui:jvmTest                 # Geteilte Logik-Tests ausführen
./gradlew :client:common-ui:build                   # Geteiltes Modul erstellen

# 🔄 Alle Client-Tests
./gradlew :client:common-ui:jvmTest :client:desktop-app:jvmTest :client:web-app:jsTest

---

Modul-Dokumentation

📖 Detaillierte Dokumentations-Links

Jedes Modul hat eine umfassende Dokumentation, die Architektur, Entwicklung, Testing und Deployment abdeckt:

• Common-UI Modul - Geteilte MVVM-Architektur, Services und Geschäftslogik
• Desktop-App Modul - Native Desktop-Anwendung mit plattformübergreifender Distribution
• Web-App Modul - Progressive Web Application mit modernen Web-Standards

🎯 Wichtige Dokumentations-Abschnitte

Jede Modul-README enthält:

• Architektur & Struktur - Detaillierte technische Architektur
• Entwicklungs-Workflow - Setup, Build und Testing-Verfahren
• API-Referenz - Vollständige API-Dokumentation mit Beispielen
• Deployment-Leitfaden - Produktions-Deployment-Anweisungen
• Fehlerbehebung - Häufige Probleme und Lösungen

---

Build & Packaging

Entwicklungs-Builds

# Alle Client-Module erstellen
./gradlew :client:build

# Einzelne Module erstellen
./gradlew :client:common-ui:build        # Geteilte Komponenten
./gradlew :client:desktop-app:build      # Desktop-Anwendung
./gradlew :client:web-app:build          # Web-Anwendung

Produktions-Packaging

Plattform	Befehl	Ausgabe
Desktop	./gradlew :client:desktop-app:createDistributable	Plattformübergreifende Installer
Web	./gradlew :client:web-app:jsBrowserProductionWebpack	Optimiertes PWA-Bundle

Distributions-Formate

Desktop-Anwendung:

• Linux: .deb Pakete
• macOS: .dmg Disk-Images
• Windows: .msi Installer

Web-Anwendung:

• Optimierte JavaScript-Bundles
• PWA-Manifest für App-Installation
• Service Worker bereit (zukünftige Erweiterung)

---

Konfiguration

Umgebungs-Konfiguration

Die Client-Anwendungen unterstützen flexible Konfiguration:

Konfiguration	Desktop	Web	Standardwert
API Basis-URL	System-Eigenschaft	Build-Zeit	http://localhost:8080
Log-Level	JVM-Args	Konsole	INFO

Desktop-Konfiguration

# Benutzerdefinierte API-URL
./gradlew :client:desktop-app:run -Dmeldestelle.api.url=https://api.production.com

# Entwicklung mit lokalem Backend
./gradlew :client:desktop-app:run -Dmeldestelle.api.url=http://localhost:8080

Web-Konfiguration

Die Web-Anwendungs-Konfiguration wird zur Build-Zeit eingebettet und kann im Build-Prozess angepasst werden.

---

Test-Strategie

Umfassende Test-Abdeckung

Modul	Test-Typ	Anzahl	Abdeckung
Common-UI	Unit + Integration	32	Geschäftslogik, MVVM, Services
Desktop-App	JVM Integration	3	Anwendungsstart, Konfiguration
Web-App	JavaScript	4	Web-spezifische Funktionalität, PWA
Gesamt	Plattformübergreifend	39	Vollständige Client-Abdeckung

Test-Ausführung

# Alle Client-Tests ausführen
./gradlew :client:common-ui:jvmTest :client:desktop-app:jvmTest :client:web-app:jsTest

# Einzelne Test-Suiten
./gradlew :client:common-ui:jvmTest      # Geteilte Geschäftslogik
./gradlew :client:desktop-app:jvmTest    # Desktop-spezifische Tests
./gradlew :client:web-app:jsTest         # Web/JS-spezifische Tests

Test-Qualitäts-Metriken

• ✅ MVVM-Architektur: Vollständiges Zustandsverwaltungs-Testing
• ✅ Ressourcenverwaltung: Memory-Leak-Präventions-Validierung
• ✅ Plattformübergreifend: Plattformspezifische Integrationstests
• ✅ API-Integration: HTTP-Service und Serialisierungs-Tests

---

Leistung & Qualität

Architektur-Vorteile

🏗️ MVVM-Implementierung:

• Ordnungsgemäße Trennung der Belange mit testbaren Komponenten
• Reaktive UI-Zustandsverwaltung mit Compose
• Ressourcen-Lebenszyklus-Verwaltung mit automatischer Bereinigung

🚀 Laufzeit-Leistung:

• Effizientes Speichermanagement durch ordnungsgemäße Disposal-Muster
• Optimierte Build-Konfigurationen für beide Plattformen
• Minimaler Overhead mit geteilter Geschäftslogik

🔧 Entwicklererfahrung:

• Hot Reload für Desktop- und Web-Entwicklung
• Umfassende Test-Infrastruktur
• Klare Dokumentation und Fehlerbehebungs-Leitfäden

Qualitätssicherung

• Test-Abdeckung: 39 umfassende Tests über alle Client-Module
• Architektur-Konformität: 100% MVVM-Muster-Implementierung
• Build-Optimierung: Moderne Gradle-Konfiguration mit Abhängigkeitsverwaltung
• Plattformübergreifend: Konsistentes Verhalten über Desktop- und Web-Plattformen

---

Produktionsbereitschaft

Desktop-Anwendung

✅ Distributionsbereit:

• Plattformübergreifende Installer (Linux, macOS, Windows)
• Native Leistung mit JVM-Optimierung
• System-Integrations-Fähigkeiten

✅ Enterprise-Features:

• Konfigurierbare API-Endpunkte
• Logging-Integration bereit
• Ressourcenverwaltung und Bereinigung

Web-Anwendung

✅ Moderne PWA:

• Progressive Web App mit Installations-Unterstützung
• Mobile-First responsives Design
• Offline-Fähigkeiten bereit (Service Worker erweiterbar)

✅ Produktionsstandards:

• Sicherheits-Header (CSP, XSS-Schutz)
• Leistungsoptimierung (Webpack, Caching)
• SEO und Barrierefreiheits-Konformität

---

API-Integration

Geteilter HTTP-Client

Alle Client-Anwendungen verwenden ein konsistentes API-Integrations-Muster:

// Geteilte Service-Schicht
class PingService(
    private val baseUrl: String,
    private val httpClient: HttpClient
) {
    suspend fun ping(): Result<PingResponse>
    fun close()
}

// Plattformspezifische Engines
// Desktop: Ktor CIO Engine
// Web: Ktor JS Engine

API-Konfiguration

Umgebung	API Basis-URL	Konfigurationsmethode
Entwicklung	http://localhost:8080	Standard-Konfiguration
Staging	https://staging-api.example.com	System-Eigenschaften / Build-Konfiguration
Produktion	https://api.example.com	System-Eigenschaften / Build-Konfiguration

---

Migrations- & Upgrade-Leitfaden

Von der vorherigen Architektur

Die Client-Architektur wurde vollständig modernisiert:

Vorher (Komponentenbasiert):

• Vermischte Belange in UI-Komponenten
• Manuelle Zustandsverwaltung
• Speicherleck-Potenzial
• Begrenzte plattformübergreifende Wiederverwendung

Aktuell (MVVM):

• Saubere Architektur mit getrennten Belangen
• Reaktive Zustandsverwaltung mit Compose
• Automatische Ressourcenbereinigung
• Maximale Code-Wiederverwendung über Plattformen

Breaking Changes

Keine - Das Architektur-Upgrade behielt die Rückwärtskompatibilität für alle öffentlichen APIs bei.

---

Zukünftige Erweiterungen

Roadmap-Prioritäten

1. Erweiterte PWA-Features

   • Service Worker-Implementierung für vollständige Offline-Unterstützung
   • Push-Benachrichtigungs-Integration
   • Hintergrund-Sync-Fähigkeiten

2. Desktop-Erweiterungen

   • Native System-Integration (Benachrichtigungen, Dateidialoge)
   • Auto-Update-Mechanismen
   • Erweiterte Logging-Konfiguration

3. Test-Erweiterung

   • End-to-End-Testing über Plattformen
   • Visual Regression Testing
   • Performance-Benchmarking

4. Monitoring-Integration

   • Fehlerberichterstattung und Analytik
   • Performance-Überwachung
   • Benutzerverhalten-Analytik

---

Fehlerbehebung

Häufige Probleme über alle Plattformen

Problem	Plattform	Lösung
API-Verbindungsfehler	Alle	Basis-URL-Konfiguration und Netzwerkkonnektivität überprüfen
Build-Fehler	Alle	Build-Verzeichnis bereinigen: ./gradlew clean
Test-Ausführungsprobleme	Alle	Plattformspezifische Anforderungen prüfen (JDK, Node.js)
Hot Reload funktioniert nicht	Web	Dev-Server neu starten, File Watcher prüfen

Plattformspezifische Probleme

Desktop:

• Fenster wird nicht angezeigt → Display-Einstellungen und Fensterzustand prüfen
• SLF4J-Warnungen → Logback-Abhängigkeit hinzufügen (nicht kritisch)

Web:

• Weißer Bildschirm beim Laden → Browser-Konsole auf JavaScript-Fehler prüfen
• PWA installiert nicht → HTTPS und manifest.json verifizieren

Debug-Befehle

# Umfassende Build-Analyse
./gradlew :client:build --scan

# Abhängigkeitskonflikt-Analyse
./gradlew :client:dependencies

# Ausführliche Test-Ausführung
./gradlew :client:common-ui:jvmTest --info

---

Mitwirken

Entwicklungs-Workflow

1. Umgebung einrichten

   # Voraussetzungen überprüfen
   java -version    # Sollte JDK 21 anzeigen
   node --version   # Sollte Node.js ≥ 20 anzeigen
   
   # Erstellen und validieren
   ./gradlew :client:build
   

2. Entwicklungsprozess

   # Üblicher Entwicklungszyklus
   ./gradlew :client:common-ui:jvmTest      # Geteilte Logik testen
   ./gradlew :client:desktop-app:run        # Desktop-Integration testen
   ./gradlew :client:web-app:jsTest         # Web-Kompatibilität testen
   

3. Qualitätssicherung

   # Vollständige Test-Suite
   ./gradlew :client:common-ui:jvmTest :client:desktop-app:jvmTest :client:web-app:jsTest
   
   # Architektur-Validierung
   ./gradlew :client:build --scan
   

Code-Standards

• Architektur: MVVM-Muster und Trennung der Belange beibehalten
• Testing: Tests für neue Funktionalität über alle betroffenen Module hinzufügen
• Dokumentation: Modul-spezifische READMEs für Änderungen aktualisieren
• Kompatibilität: Sicherstellen, dass Änderungen auf Desktop- und Web-Plattformen funktionieren

Pull Request Checkliste

• Alle bestehenden Tests bestehen über alle Client-Module
• Neue Funktionalität beinhaltet angemessene Test-Abdeckung
• MVVM-Architektur-Muster beibehalten
• Plattformübergreifende Kompatibilität verifiziert
• Modul-spezifische Dokumentation aktualisiert
• Leistungsauswirkungen bewertet und dokumentiert

---

Kontakt & Support

Dokumentations-Struktur

Für detaillierte Informationen zu spezifischen Modulen:

• Common-UI: README-CLIENT-COMMON-UI.md
• Desktop-App: README-CLIENT-DESKTOP-APP.md
• Web-App: README-CLIENT-WEB-APP.md

Schnellreferenz

Aufgabe	Befehl
Desktop-App starten	./gradlew :client:desktop-app:run
Web-Dev-Server starten	./gradlew :client:web-app:jsBrowserDevelopmentRun
Alle Tests ausführen	./gradlew :client:common-ui:jvmTest :client:desktop-app:jvmTest :client:web-app:jsTest
Für Produktion erstellen	./gradlew :client:build
Desktop-Installer erstellen	./gradlew :client:desktop-app:createDistributable
Web-Produktions-Bundle erstellen	./gradlew :client:web-app:jsBrowserProductionWebpack

---

Client-Status: ✅ Produktionsbereit Architektur: ✅ MVVM Vollständig Test-Abdeckung: ✅ Umfassend (39 Tests) Plattformübergreifend: ✅ Desktop + Web PWA Dokumentation: ✅ Vollständig

Zuletzt aktualisiert: 16. August 2025