# 🖥️ 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

```bash
# 🖥️ 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](common-ui/README-CLIENT-COMMON-UI.md)** - Geteilte MVVM-Architektur, Services und Geschäftslogik
- **[Desktop-App Modul](desktop-app/README-CLIENT-DESKTOP-APP.md)** - Native Desktop-Anwendung mit plattformübergreifender Distribution
- **[Web-App Modul](web-app/README-CLIENT-WEB-APP.md)** - 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

```bash
# 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

```bash
# 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

```bash
# 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:

```kotlin
// 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

```bash
# 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**
   ```bash
   # Voraussetzungen überprüfen
   java -version    # Sollte JDK 21 anzeigen
   node --version   # Sollte Node.js ≥ 20 anzeigen

   # Erstellen und validieren
   ./gradlew :client:build
   ```

2. **Entwicklungsprozess**
   ```bash
   # Ü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**
   ```bash
   # 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](common-ui/README-CLIENT-COMMON-UI.md)
- **Desktop-App**: [README-CLIENT-DESKTOP-APP.md](desktop-app/README-CLIENT-DESKTOP-APP.md)
- **Web-App**: [README-CLIENT-WEB-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*