docs: enhance local dev docs, update Docker Compose, and archive old journals

Added Mailpit setup and updated Keycloak configuration in local development runbooks. Improved Docker Compose stability with updated service dependencies and configurations. Archived outdated journal entries and documents for better organization.
This commit is contained in:
2026-01-20 14:00:09 +01:00
parent 5dc8f18201
commit 46361185d0
56 changed files with 596 additions and 1832 deletions
@@ -2,7 +2,7 @@
type: Roadmap
status: ACTIVE
owner: Lead Architect
last_update: 2026-01-15
last_update: 2026-01-20
---
# MASTER ROADMAP Q1 2026: "Operation Tracer Bullet"
@@ -12,8 +12,8 @@ Wir validieren die gesamte Architektur-Kette (Frontend -> Gateway -> Service ->
**Aktueller technischer Stand:**
* Build System: ✅ Grün (Gradle, Kotlin 2.3, Spring Boot 3.5.9, Spring Cloud 2025.0.1).
* Code-Basis: ✅ `ping-service` existiert rudimentär.
* Infrastruktur: ⚠️ Muss gehärtet werden.
* Code-Basis: ✅ `ping-service` existiert, Delta-Sync implementiert.
* Infrastruktur: ✅ Docker Environment stabil, Tracing aktiv.
---
@@ -25,14 +25,14 @@ Wir validieren die gesamte Architektur-Kette (Frontend -> Gateway -> Service ->
#### 👷 Agent: Senior Backend Developer
Deine Aufgabe ist es, den `ping-service` von einem "Hello World" zu einem Enterprise-Microservice zu machen.
* [ ] **Security Implementation (Prio 1):**
* [x] **Security Implementation (Prio 1):**
* Konfiguriere Spring Security als OAuth2 Resource Server.
* Implementiere RBAC (Role Based Access Control) für `/ping/secure`.
* Stelle sicher, dass Tokens vom Keycloak (Docker) korrekt validiert werden.
* [ ] **Resilience (Prio 2):**
* Aktiviere Resilience4j CircuitBreaker für Datenbank-Zugriffe.
* Implementiere Fallbacks (z.B. "Degraded Mode" wenn DB weg ist).
* [ ] **Observability (Prio 3):**
* [x] **Observability (Prio 3):**
* Aktiviere Spring Boot Actuator (Health, Info, Prometheus).
* Stelle sicher, dass Tracing-IDs (Micrometer/Zipkin) durchgereicht werden.
* [ ] **Persistence Härtung:**
@@ -42,7 +42,7 @@ Deine Aufgabe ist es, den `ping-service` von einem "Hello World" zu einem Enterp
#### 🏗️ Agent: Infrastructure & DevOps
Deine Aufgabe ist die Stabilität der Laufzeitumgebung.
* [ ] **Docker Environment:**
* [x] **Docker Environment:**
* Stabilisiere `docker-compose.yaml`. Alle Services (Consul, Keycloak, Postgres, Zipkin) müssen zuverlässig starten.
* Prüfe Migration von Redis zu **Valkey** (Open Source Härtung), wie im Hardening-Dokument vorgeschlagen.
* [ ] **Gateway Config:**
@@ -71,7 +71,7 @@ Deine Aufgabe ist die Anbindung des gehärteten Backends.
*Ziel: Datenkonsistenz auch bei Netzwerk-Verlust.*
#### 🤝 Joint Task Force (Backend & Frontend)
* [ ] **Sync-Protokoll:**
* [x] **Sync-Protokoll:**
* Implementierung des Delta-Syncs basierend auf `PingEvent` (UUIDv7 + Timestamp).
* Frontend: Speicherung in SQLDelight (lokal).
* Backend: Bereitstellung des Sync-Endpunkts.
@@ -0,0 +1,39 @@
---
type: ADR
status: ACTIVE
owner: Lead Architect
last_update: 2026-01-20
---
# ADR-0013: Stabilisierung des Tech-Stacks (Januar 2026)
## Status
Angenommen
## Kontext
Das Projekt "Meldestelle" setzt auf einen sehr modernen Technologie-Stack (Java 25, Kotlin 2.3.0, Spring Boot 3.5.9). Eine Analyse im Januar 2026 hat jedoch kritische Versionskonflikte aufgedeckt, die die Stabilität des Builds und der Laufzeitumgebung gefährden.
1. **Spring Cloud Konflikt:** Der Release Train `2025.1.0` (Oakwood) ist für Spring Boot 4.0 konzipiert und inkompatibel mit Spring Boot 3.5.9 (führt zu `NoSuchMethodError`).
2. **Compose Multiplatform:** Version `1.9.3` führt zu Compiler-Crashes in Verbindung mit Kotlin 2.3.0.
3. **Exposed:** Version `0.61.0` ist veraltet und inkompatibel mit Kotlin 2.3.0.
## Entscheidung
Wir führen folgende Korrekturen am Tech-Stack durch, um eine stabile "Best Compatibility List" zu etablieren:
1. **Spring Cloud Downgrade:** Wechsel auf Release Train `2025.0.1` (Northfields), der offiziell für Spring Boot 3.5.x freigegeben ist.
2. **Compose Multiplatform Upgrade:** Wechsel auf `1.10.0-rc02` (oder stable), um volle Kotlin 2.3.0 Kompatibilität zu gewährleisten.
3. **Exposed Upgrade:** Wechsel auf `1.0.0-rc-4` (oder neuer), um Bytecode-Inkompatibilitäten zu beheben.
4. **Micrometer Upgrade:** Explizites Setzen von Version `1.16.1` für verbesserten Java 25 (Virtual Threads) Support.
## Konsequenzen
### Positiv
* **Stabilität:** Der Build und die Application Context Initialisierung sind wieder stabil.
* **Zukunftssicherheit:** Wir nutzen weiterhin die neuesten Features von Java 25 und Kotlin 2.3.0, aber in einer validierten Kombination.
* **Wartbarkeit:** Die `libs.versions.toml` spiegelt nun eine getestete Konfiguration wider.
### Negativ
* **Migrationsaufwand:** Einmaliger Aufwand zur Anpassung der `libs.versions.toml` und ggf. kleinerer API-Änderungen in Exposed/Compose.
## Compliance
Diese Entscheidung ist bindend für alle Module. Abweichungen müssen durch ein neues ADR genehmigt werden.