fixing Trace Bullet

2025-09-15 21:23:33 +02:00
parent ea560fc221
commit f81e52388c
17 changed files with 331 additions and 25 deletions
@@ -0,0 +1,47 @@
+# Client Architecture (Kotlin Multiplatform)
+
+This document summarizes the post-migration client setup and how it integrates with the overall architecture.
+
+## Overview
+- Single Kotlin Multiplatform module `:client`
+- Targets:
+  - Desktop (JVM) using Compose Desktop
+  - Web (Browser) using Compose for Web (WASM)
+- Shared UI and logic in `commonMain`; thin platform entry points in `jvmMain` and `wasmJsMain`
+
+## Interaction with Backend
+- Gateway exposes unified API under `/api/...`
+- Client calls go through the gateway:
+  - Desktop (JVM): Base URL from env `API_BASE_URL` (defaults to `http://localhost:8081`)
+  - Web (WASM): Same-origin requests (e.g. `/api/ping`) – serve WASM bundle from the same host as the gateway or configure a reverse proxy
+
+## Build & Run
+- Desktop (JVM): `./gradlew :client:run`
+- Web (WASM):
+  - Dev server with live reload: `./gradlew :client:wasmJsBrowserDevelopmentRun`
+  - Production build: `./gradlew :client:wasmJsBrowserProductionWebpack`
+
+Artifacts:
+- Desktop distributions: `client/build/compose/binaries`
+- WASM production build: `client/build/dist/wasmJs/productionExecutable`
+
+## WASM Bundle Analysis & Optimization
+- Enable bundle analysis: `ANALYZE_BUNDLE=true ./gradlew :client:wasmJsBrowserProductionWebpack`
+- Webpack augmentations in `client/webpack.config.d/`:
+  - `bundle-analyzer.js`: logs asset sizes and optimization hints
+  - `wasm-optimization.js`: enables tree-shaking, chunk splitting, and production optimizations
+- Client-side Ktor setup is minimized to reduce bundle size (no extra plugins, lean JSON config)
+
+## Testing Notes
+- Browser-based JS tests (Karma/ChromeHeadless) are disabled to avoid local sandbox/headless issues
+- JS tests run under Node/Mocha
+- Integration tests for backend modules are available in their respective modules; run all tests with `./gradlew test`
+
+## Current Limitations / TODOs
+- Domain UIs (masterdata, members, horses, events) to be implemented in the client
+- Authentication/session handling (Keycloak) to be integrated in the client
+- Optional: add lightweight E2E (smoke) tests that traverse the full flow via the gateway
+
+## Relation to C4 Diagrams
+- See `docs/architecture/c4/` for Context and Container diagrams
+- The `:client` module represents the User Interface container (Desktop/Web) communicating with the API Gateway container
@@ -92,3 +92,29 @@ Phase 4: Gesamtsystem testen und aufräumen
 [ ] Wenn alles funktioniert, den aktuellen Stand in Git committen (z.B. "feat: Add stable infrastructure baseline").

 [ ] Das :temp:ping-service-Modul und das :client:web-app-Modul in settings.gradle.kts wieder auskommentieren, um den Boden für den ersten echten Fach-Service vorzubereiten.
+
+
+---
+
+## Status-Update (September 2025)
+
+Ergebnis: Der Trace-Bullet ist abgeschlossen. Folgende Punkte sind erledigt:
+- [x] Gateway konfiguriert und startbar (inkl. Actuator/Prometheus, Tracing via monitoring-client)
+- [x] Ping-Service implementiert, bei Consul registriert und via Gateway erreichbar
+- [x] Circuit Breaker (Resilience4j) aktiv inkl. Fallbacks
+- [x] Client (Desktop/Web) führt Ping über Gateway aus
+- [x] Micrometer Tracing + Zipkin im Ping-Service und Gateway aktiv
+- [x] CORS zentral im Gateway (globalcors) aktiv, service-lokales CORS entfernt
+- [x] Einheitliches Logging-Pattern (traceId/spanId) über Logback
+- [x] Prometheus-Scrapes für Gateway und Ping-Service
+
+Zusätzlich eingeführt:
+- Smoke-Skripte: `scripts/smoke/zipkin_smoke.sh` und `scripts/smoke/prometheus_smoke.sh`
+- API-Härtung: `/ping` liefert nun status, timestamp, service
+- Health Probes: Actuator-Probes für liveness/readiness aktiviert
+
+Nächste Schritte (optional):
+- [ ] Client-Auth (Keycloak) integrieren und End-to-End testen
+- [ ] Weitere Services (members, horses, events) sukzessive ans Gateway hängen und observability prüfen
+- [ ] Sampling-Rate für Produktion reduzieren (TRACING_SAMPLING_PROBABILITY=0.1)
+- [ ] Optional: JSON-Logging für Containerbetrieb