meldestelle/client/web-app

Meldestelle Web-App

Eine moderne Web-Anwendung basierend auf Compose for Web (Compose Multiplatform) für das Meldestelle-Projekt.

📋 Überblick

Diese Web-Anwendung implementiert das Frontend für das Meldestelle-System unter Verwendung von Compose for Web. Sie folgt dem Architekturprinzip der maximalen Code-Wiederverwendung durch die Nutzung des commonMain-Source-Sets von Kotlin Multiplatform.

Technologie-Stack

• Frontend Framework: Compose for Web (Compose Multiplatform 1.8.2)
• Programmiersprache: Kotlin/JS
• Build-System: Gradle 8.10
• HTTP-Client: Ktor Client
• UI-Komponenten: Compose Material 3 (aus commonMain)
• Bundler: Webpack (über Kotlin/JS Plugin)
• Container: Nginx (Production)

🏗️ Architektur

client/web-app/
├── src/
│   └── jsMain/
│       ├── kotlin/at/mocode/client/web/
│       │   └── main.kt                 # Entry Point
│       └── resources/
│           └── index.html              # HTML Template
├── build.gradle.kts                    # Build Konfiguration
└── build/                              # Build Artefakte
    └── dist/js/productionExecutable/   # Produktionsversion

Design Prinzipien

1. Code-Wiederverwendung: Maximale Nutzung des client:common-ui Moduls
2. Compose for Web: Deklarative UI mit @Composable Funktionen
3. State Management: Zustandsverwaltung über ViewModels im commonMain
4. Plattform-Trennung: UI-Code in jsMain, Logik in commonMain

🚀 Schnellstart

Voraussetzungen

• Java 21+
• Docker und Docker Compose
• Node.js 18+ (wird automatisch im Container installiert)

Entwicklung starten

Mit Docker (Empfohlen)

# Web-App im Entwicklungsmodus starten
docker compose -f docker-compose.yml -f docker-compose.clients.yml up -d web-app

# Anwendung ist verfügbar unter:
# http://localhost:3000

Lokale Entwicklung

# Abhängigkeiten installieren und Entwicklungsserver starten
./gradlew :client:web-app:jsBrowserDevelopmentRun

# Anwendung läuft auf http://localhost:8080

Produktionsbuild

# Optimierte JavaScript-Bundles erstellen
./gradlew :client:web-app:jsBrowserDistribution

# Artefakte befinden sich in:
# client/web-app/build/dist/js/productionExecutable/

🔧 Entwicklung

Projekt-Struktur

// main.kt - Entry Point
fun main() {
    renderComposable(rootElementId = "root") {
        WebApp()
    }
}

@Composable
fun WebApp() {
    // Verwendet die gemeinsame App-Komponente aus commonMain
    App()
}

Hot-Reload

Die Entwicklungsumgebung unterstützt Hot-Reload:

• Änderungen an Kotlin-Code werden automatisch neu kompiliert
• Browser wird automatisch aktualisiert
• Schnelle Entwicklungszyklen durch Webpack Dev Server

Build-Konfiguration

Die build.gradle.kts konfiguriert:

kotlin {
    js(IR) {
        browser {
            commonWebpackConfig {
                outputFileName = "web-app.js"
                // Webpack optimization directory
                configDirectory = project.projectDir.resolve("webpack.config.d")
            }
            webpackTask {
                mainOutputFileName = "web-app.js"
            }
        }
        binaries.executable()
    }
}

Webpack-Optimierungen

Das Projekt verwendet erweiterte Webpack-Optimierungen für bessere Performance:

Code Splitting

• Separate Chunks: Bundle wird in ~60 kleinere, cacheable Dateien aufgeteilt
• Vendor Chunks: Große Libraries (Kotlin stdlib, Compose runtime, Coroutines) werden separat geladen
• Lazy Loading: Verbessertes Caching durch getrennte Vendor- und App-Code-Chunks

Bundle-Größenoptimierung

• Tree Shaking: Entfernt ungenutzten Code
• Minification: Aggressive Komprimierung im Produktionsbuild
• Scope Hoisting: Optimiert JavaScript-Execution
• Performance Budget: Warnt bei zu großen Bundles (500KB pro Asset, 800KB Gesamt)

Generierte Chunks (Beispiel)

web-app-runtime.js          1.67 KiB  (Runtime)
web-app.js                  482 bytes (Main App)
web-app-compose-runtime-*.js 274 KiB   (Compose Framework)
web-app-kotlin-stdlib.js    165 KiB   (Kotlin Standard Library)
web-app-coroutines.js       119 KiB   (Kotlinx Coroutines)
web-app-vendors-*.js        1.17 MiB  (Weitere Dependencies)

**Abhängigkeiten:**
- `compose.web.core` - Compose for Web Framework
- `compose.runtime` - Compose Runtime
- `project(":client:common-ui")` - Gemeinsame UI-Komponenten
- `kotlinx-coroutines-core-js` - Coroutines für Web

## 🌐 Deployment

### Docker Container

Die Anwendung wird als Docker-Container deployed:

```dockerfile
# Multi-stage Build
FROM gradle:8.10-jdk21 AS builder
# ... Build Phase

FROM nginx:1.25-alpine AS production
# ... Production Phase

Features:

• Multi-stage Build für optimale Image-Größe
• Nginx als Static File Server
• Health Checks
• Security Headers
• Gzip Kompression

Konfiguration

Umgebungsvariablen:

• NODE_ENV: Entwicklungs-/Produktionsmodus
• API_BASE_URL: Backend API URL
• APP_TITLE: Anwendungstitel
• APP_VERSION: Versionsnummer

Health Checks

# Container Health Check
curl --fail http://localhost:3000/health

# Antwort: {"status":"ok","service":"web-app"}

🔗 Integration

Backend-Kommunikation

Die Web-App kommuniziert mit dem Backend über:

• API Gateway: http://api-gateway:8081
• REST APIs: Über Ktor Client
• WebSocket: Für Realtime-Updates (geplant)

Gemeinsame Komponenten

Nutzt Komponenten aus client:common-ui:

• ViewModels: PingViewModel für Backend-Tests
• UI-Komponenten: App, PingScreen
• Services: PingService für HTTP-Aufrufe
• Models: Datenklassen und UI-States

Beispiel Integration

@Composable
fun WebApp() {
    // Verwendet die gemeinsame App-Komponente
    // Diese enthält Material 3 Komponenten und ViewModels
    App(baseUrl = "http://localhost:8081")
}

📊 Build-Artefakte

Nach dem Build werden folgende Dateien generiert:

build/dist/js/productionExecutable/
├── web-app.js              # Hauptanwendung (minifiziert)
├── web-app.js.map          # Source Maps
├── 731.js                  # Code Splitting Chunk
├── index.html              # HTML Template
├── skiko.wasm              # Compose Runtime (WebAssembly)
└── skiko.js                # Compose JavaScript Runtime

🧪 Testing

Entwicklungstests

# Backend-Konnektivität testen
# Öffne http://localhost:3000
# Klicke "Ping Backend" Button

Build-Validierung

# Build ohne Ausführung testen
./gradlew :client:web-app:jsBrowserDevelopmentRun --dry-run

# Produktionsbuild testen
./gradlew :client:web-app:jsBrowserDistribution

📚 Weiterführende Dokumentation

• Web-App Guideline - Architektur-Richtlinien
• Docker README - Container-Dokumentation
• Compose for Web Docs - Offizielle Dokumentation

🔍 Troubleshooting

Häufige Probleme

Problem: Cannot connect to backend

# Lösung: Backend Services starten
docker-compose -f docker-compose.yml -f docker-compose.services.yml up -d

Problem: Module build failed

# Lösung: Clean Build
./gradlew :client:web-app:clean :client:web-app:jsBrowserDevelopmentRun

Problem: Port 3000 already in use

# Lösung: Port in docker-compose.clients.yml ändern
ports:
  - "3001:3000"  # Externer Port ändern

Logs und Debugging

# Container Logs anzeigen
docker logs meldestelle-web-app

# Build Logs mit Details
./gradlew :client:web-app:jsBrowserDevelopmentRun --info --stacktrace

---

Letzte Aktualisierung: 2025-09-10 Version: 1.0.0