mocode-software/meldestelle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: consolidate roadmaps and update architecture documentation

Browse Source 
Replaced fragmented roadmaps with a single MASTER_ROADMAP for Q1 2026 as the authoritative source. Deprecated outdated roadmap files and updated Architect playbook to reflect new ownership and delegation responsibilities. Introduced architecture improvement proposals and added related documents for enhanced collaboration and knowledge sharing.
This commit is contained in:
Stefan Mogeritsch 2026-01-16 10:42:34 +01:00
parent 4b9772ff6b
commit 2dc3c4154b
9 changed files with 259 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
backend/services/ping/ping-service/src/main/kotlin/at/mocode/ping/infrastructure/SecurityConfig.kt Normal file
View File

@ -0,0 +1,32 @@
package at.mocode.ping.infrastructure
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.config.annotation.web.builders.HttpSecurity
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity
import org.springframework.security.web.SecurityFilterChain
@Configuration
@EnableWebSecurity
class SecurityConfig {
@Bean
fun filterChain(http: HttpSecurity): SecurityFilterChain {
http
.authorizeHttpRequests { auth ->
auth
// Public endpoints
.requestMatchers("/actuator/**").permitAll()
.requestMatchers("/ping/simple", "/ping/enhanced", "/ping/health", "/ping/history").permitAll()
// Secure endpoints
.requestMatchers("/ping/secure").authenticated()
// Default deny
.anyRequest().authenticated()
}
.oauth2ResourceServer { oauth2 ->
oauth2.jwt { }
}
return http.build()
}
}

9
core/core-utils/src/commonMain/kotlin/at/mocode/core/sync/Syncable.kt Normal file
View File

@ -0,0 +1,9 @@
package at.mocode.core.sync
/**
* Interface for entities that can be synchronized.
*/
interface Syncable {
val id: String
val lastModified: Long
}

85
docs/01_Architecture/MASTER_ROADMAP_2026_Q1.md Normal file
View File

@ -0,0 +1,85 @@
# MASTER ROADMAP Q1 2026: "Operation Tracer Bullet"
**Status:** ACTIVE / SINGLE SOURCE OF TRUTH
**Owner:** Lead Software Architect
**Letztes Update:** 15.01.2026
---
## 1. Strategisches Ziel
Wir validieren die gesamte Architektur-Kette (Frontend -> Gateway -> Service -> DB) anhand des **Ping-Service**. Dieser Service dient als **technischer Blueprint** (Vorlage) für alle kommenden Fach-Services. Er muss "Production Ready" gehärtet sein, bevor wir Fachlichkeit implementieren.
**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.
---
## 2. Arbeitsaufträge an die AGENTS (Phasenplan)
### PHASE 1: Backend Hardening & Infrastructure (Woche 2)
*Ziel: Der Ping-Service läuft sicher, stabil und beobachtbar in der Docker-Umgebung.*
#### 👷 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):**
* 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):**
* Aktiviere Spring Boot Actuator (Health, Info, Prometheus).
* Stelle sicher, dass Tracing-IDs (Micrometer/Zipkin) durchgereicht werden.
* [ ] **Persistence Härtung:**
* Integriere **Flyway** für Datenbank-Migrationen (kein `ddl-auto` in Prod!).
* Implementiere einen "Deep Health Check" (`/actuator/health`), der DB und Cache aktiv prüft.
#### 🏗️ Agent: Infrastructure & DevOps
Deine Aufgabe ist die Stabilität der Laufzeitumgebung.
* [ ] **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:**
* Konfiguriere Routen und CircuitBreaker im Spring Cloud Gateway für den `ping-service`.
---
### PHASE 2: Frontend Integration (Woche 3)
*Ziel: Das Frontend kann authentifiziert mit dem Backend sprechen.*
#### 🎨 Agent: KMP Frontend Expert
Deine Aufgabe ist die Anbindung des gehärteten Backends.
* [ ] **HTTP Client Core:**
* Konfiguriere Ktor Client mit `AuthInterceptor` (Bearer Token Injection).
* Implementiere Global Error Handling (Umgang mit 401, 403, 503).
* [ ] **Authentication Flow:**
* Implementiere den OIDC Login Flow (Keycloak) für Desktop und Web.
* Speichere Tokens sicher im Memory (AuthState).
* [ ] **UI Implementation:**
* Baue einen Debug-Screen, der die Endpunkte `/ping/simple` und `/ping/secure` visualisiert.
---
### PHASE 3: Offline & Sync (Woche 4)
*Ziel: Datenkonsistenz auch bei Netzwerk-Verlust.*
#### 🤝 Joint Task Force (Backend & Frontend)
* [ ] **Sync-Protokoll:**
* Implementierung des Delta-Syncs basierend auf `PingEvent` (UUIDv7 + Timestamp).
* Frontend: Speicherung in SQLDelight (lokal).
* Backend: Bereitstellung des Sync-Endpunkts.
---
## 3. Definition of Done (für Phase 1 & 2)
1. `docker compose up` startet den kompletten Stack fehlerfrei.
2. Frontend-User kann sich einloggen (Keycloak).
3. Frontend zeigt Daten vom `ping-service` an.
4. Beim Abschalten der DB zeigt der Service einen sauberen Fallback (CircuitBreaker offen).
5. In Zipkin ist der komplette Request-Trace (Frontend -> Gateway -> Service -> DB) sichtbar.

64
docs/01_Architecture/Roadmap_2026_Q1.md Normal file
View File

@ -0,0 +1,64 @@
# Roadmap Q1 2026: "Operation Tracer Bullet"
**Status:** Draft
**Owner:** Lead Software Architect
**Ziel:** Stabilisierung der Architektur und Durchstich ("Tracer Bullet") mit dem `ping-service`.
---
## Phase 1: Fundament & Stabilisierung (Woche 1-2)
Das Ziel dieser Phase ist es, die Entwicklungsumgebung (Build, Docker, Dependencies) so zu stabilisieren, dass alle Entwickler (und Agenten) reibungslos arbeiten können.
### 1.1 Build-System & Dependencies (Architect)
- [ ] **Spring Cloud Fix:** Downgrade von `2025.1.0` (Oakwood) auf `2025.0.1` (Northfields) in `libs.versions.toml` und `platform-bom`.
- [ ] **Wasm Build Fix:** Analyse und Behebung der `Worker` / `Unresolved reference` Fehler im Frontend-Build. Ggf. explizite Dependency für `kotlinx-browser` prüfen.
- [ ] **Dependency Cleanup:** Entfernen von redundanten Datenbank-Libs (Entscheidung: SQLDelight für KMP Client, Room entfernen wenn nicht genutzt; Exposed im Backend auf `1.0.0-rc-4` heben).
- [ ] **Micrometer Upgrade:** Explizites Setzen von Micrometer `1.16.1` für besseren Java 25 Support.
### 1.2 Infrastruktur & Docker (DevOps)
- [ ] **Gateway CircuitBreaker:** Behebung des `ClassNotFoundException` / `NoSuchMethodError` im Gateway (vermutlich Folge des Spring Cloud Konflikts).
- [ ] **Docker Stabilität:** Sicherstellen, dass `docker compose up` zuverlässig alle Services (Consul, Keycloak, Postgres) startet und vernetzt.
- [ ] **Keycloak Config:** Validierung der Realm-Konfiguration (`meldestelle`) und der Client-Scopes für den `ping-service`.
---
## Phase 2: Backend Implementation "Ping" (Woche 2-3)
Implementierung des ersten vertikalen Durchstichs.
### 2.1 Modul-Struktur & API (Backend Dev)
- [ ] **Refactoring `core-utils`:** Verschieben von JVM-spezifischem Code (`DatabaseUtils`) nach `:backend:infrastructure:persistence`. `core-utils` muss "pure KMP" sein.
- [ ] **API Definition:** Erstellung von `:contracts:ping-api` mit KMP-kompatiblen DTOs (`PingResponse`).
### 2.2 Service Implementation (Backend Dev)
- [ ] **Ping Service:** Implementierung von `:backend:services:ping:ping-service` mit Spring Boot 3.5.9.
- [ ] **Security:** Integration von OAuth2 Resource Server (Keycloak) und Absicherung des `/secure` Endpoints.
- [ ] **Discovery:** Registrierung bei Consul.
- [ ] **Observability:** Tracing mit Zipkin und Metrics mit Prometheus aktivieren.
---
## Phase 3: Frontend Integration (Woche 3-4)
Anbindung des Frontends an den neuen Service.
### 3.1 HTTP Client & Sync (Frontend Expert)
- [ ] **Ktor Client:** Konfiguration des HTTP-Clients für die Kommunikation mit dem Gateway (`http://localhost:8080`).
- [ ] **Auth:** Implementierung des OIDC-Flows im Frontend (Login via Keycloak), Speichern des Tokens.
- [ ] **Integration:** Aufruf von `/api/ping` und `/api/ping/secure` und Anzeige im UI.
### 3.2 Offline-Sync Basis (Frontend Expert)
- [ ] **Sync-Logik:** Erste Implementierung eines Sync-Mechanismus (z.B. Queue für Offline-Requests) basierend auf SQLDelight.
---
## Phase 4: Review & Hardening (Woche 4)
### 4.1 Quality Assurance (QA Specialist)
- [ ] **Integrationstests:** Automatisierte Tests, die den gesamten Flow (Frontend -> Gateway -> Service) prüfen.
- [ ] **Lasttests:** Einfache Lasttests auf den `ping-service` zur Validierung der Virtual Threads.
### 4.2 Documentation (Curator)
- [ ] **Update Docs:** Aktualisierung der Architektur-Dokumentation basierend auf den Erkenntnissen.
- [ ] **Onboarding:** Sicherstellen, dass neue Entwickler das Projekt mit einem Befehl starten können.

54
docs/01_Architecture/Roadmap_System_Hardening.md
View File

@ -1,53 +1,9 @@
# Roadmap: System-Instandsetzung & Härtung (via Ping-Service)
# DEPRECATED
Diese Roadmap beschreibt den Plan, den **Ping-Service** als Speerspitze für die technische Instandsetzung und Härtung der gesamten Microservices-Infrastruktur zu nutzen.
⚠️ **Dieses Dokument ist veraltet.**
**Status:** Entwurf (Bereit für Start am 15.01.2026)
**Lead:** Software Architect
Bitte nutze ausschließlich die **[MASTER ROADMAP](MASTER_ROADMAP_2026_Q1.md)** für aktuelle Aufgaben und Planung.
---
## Phase 1: Infrastruktur-Diagnose (Instandsetzung)
*Ziel: Sicherstellen, dass alle Basis-Komponenten stabil miteinander sprechen.*
- [ ] **Deep-Health-Check im Ping-Service:**
- Implementierung eines `/api/v1/ping/deep` Endpunkts.
- Aktive Prüfung der PostgreSQL-Verbindung (via `Exposed`).
- Aktive Prüfung der Cache-Verbindung (Valkey/Redis via `Lettuce`).
- Validierung der Consul-Registrierung und Config-Abfrage.
- [ ] **Infrastruktur-Migration (Open Source Härtung):**
- Umstellung von Redis auf **Valkey** im `docker-compose.yaml`.
- Anpassung der Verbindungs-Parameter im Ping-Service.
## Phase 2: Resilience & Stabilität (Härtung)
*Ziel: Fehlertoleranz gegenüber Infrastruktur-Ausfällen.*
- [ ] **Resilience4j Integration:**
- Konfiguration eines Circuit Breakers für DB-Zugriffe im Ping-Service.
- Implementierung eines Fallback-Mechanismus (z.B. "Degraded Mode" Antwort).
- [ ] **Timeout-Härtung:**
- Definition und Test von strikten Connect- und Read-Timeouts in der `application.yaml`.
- [ ] **Gateway-Integration:**
- Test des Rate-Limitings am Gateway speziell für den Ping-Service.
## Phase 3: Security & Observability
*Ziel: Absicherung der Kommunikationswege und lückenlose Überwachung.*
- [ ] **Security-Chain Validierung:**
- Aktivierung der JWT-Prüfung im Ping-Service.
- Test der "Service-to-Service" Kommunikation mit Mock-Tokens.
- [ ] **Tracing-Check:**
- Verifikation der Micrometer Tracing Integration (Trace-IDs in Logs und Zipkin).
## Phase 4: Standardisierung (Blueprint)
*Ziel: Übertragung der Erkenntnisse auf alle anderen Services.*
- [ ] **Refactoring Common-Module:**
- Verschieben der bewährten Health- und Resilience-Konfigurationen in ein `core-backend` Modul.
- [ ] **Update der Dokumentation:**
- Aktualisierung der Service-Templates basierend auf dem Ping-Service "Blueprint".
---
## Nächster Schritt (Morgen):
Start mit **Phase 1**: Implementierung des `Deep-Ping` Endpunkts und Vorbereitung der Valkey-Migration.
(Originalinhalt archiviert)
...

1
docs/04_Agents/Playbooks/Architect.md
View File

@ -24,4 +24,5 @@ Deine Aufgaben:
3. Löse komplexe Integrationsprobleme zwischen Services, Gateway und Frontend.
4. Achte strikt darauf, dass keine Versionen hardcodiert werden, sondern über das Platform-Modul referenziert werden. Ausnahmen müssen dokumentiert werden.
5. Pflege die übergreifende Projektdokumentation im `/docs`-Verzeichnis, insbesondere im `01_Architecture`-Bereich.
6. Erstelle und pflege die MASTER ROADMAP. Du bist der "Hüter des Plans". Du delegierst Aufgaben an die spezialisierten Agenten (Backend, Frontend, DevOps, QA), führst sie aber nicht selbst aus, es sei denn, es betrifft direkt die Architektur oder das Build-System.
```

39
docs/05_Backend/ROADMAP.md
View File

@ -1,36 +1,9 @@
# Backend Roadmap - Meldestelle
# DEPRECATED
Dieses Dokument beschreibt die geplanten Schritte zur Weiterentwicklung der Backend-Infrastruktur. Der aktuelle Fokus liegt auf der **Härtung der Infrastruktur** unter Nutzung des `ping-service` als technischem Blueprint.
⚠️ **Dieses Dokument ist veraltet.**
## Status Quo
* **Blueprint:** `ping-service` ist funktional, dient aber nun als Zielobjekt für Infrastruktur-Verbesserungen.
* **Technologie:** Spring Boot 3.5.9, Kotlin Coroutines, PostgreSQL.
Bitte nutze ausschließlich die **[MASTER ROADMAP](../../01_Architecture/MASTER_ROADMAP_2026_Q1.md)** für aktuelle Aufgaben und Planung.
## Meilensteine (Priorisiert)
### Meilenstein 1: Infrastruktur-Härtung (Fokus: Ping-Service)
* [ ] **Observability & Monitoring:**
* Vollständige Integration von Spring Boot Actuator.
* Konfiguration von Micrometer/Prometheus Metriken.
* Logging-Standardisierung (Structured Logging/JSON für ELK/Loki).
* [ ] **Security Baseline:**
* Integration von Spring Security mit Keycloak (OAuth2/OIDC).
* Absicherung der Endpunkte im `ping-service` (RBAC).
* Validierung der JWT-Tokens am API-Gateway.
* [ ] **Resilience & Stability:**
* Härtung des Resilience4j Setups (Circuit Breaker, Bulkhead, Rate Limiter).
* Optimierung der Datenbank-Connection-Pools (HikariCP).
* Einführung von Flyway oder Liquibase für kontrollierte DB-Migrationen.
### Meilenstein 2: Build-System & CI/CD Readiness
* [ ] **Gradle Refactoring:** Umstellung auf Version Catalog (`libs.versions.toml`) für alle Backend-Module.
* [ ] **Test-Härtung:** Standardisierung der Integrationstests mit Testcontainers (Postgres, Keycloak, Redis).
* [ ] **Docker-Optimierung:** Multi-stage Builds und Distroless-Images für reduzierte Angriffsfläche.
### Meilenstein 3: Rollout auf Fach-Services
* [ ] Übertragung der gehärteten Standards vom `ping-service` auf `horses`, `members`, etc.
* [ ] Dokumentation der "Production Readiness Checklist" für neue Services.
## Nächste Schritte (Vorschlag)
1. **Audit des aktuellen `ping-service`:** Identifikation von Lücken in Security und Monitoring.
2. **Zentralisierung der Abhängigkeiten:** Einführung der `libs.versions.toml`, um eine konsistente Basis für die Härtung zu haben.
---
(Originalinhalt archiviert)
...

37
docs/90_Reports/Architecture_Improvement_Ideas_01-2026.md Normal file
View File

@ -0,0 +1,37 @@
# Vorschläge zur Verbesserung der Dokumentations- und Roadmap-Struktur
**Von:** Lead Software Architect
**An:** Documentation & Knowledge Curator
Um die Fragmentierung der Dokumentation zu vermeiden und die Zusammenarbeit der Agenten zu optimieren, schlage ich folgende Strukturverbesserungen vor:
## 1. Roadmap-Hierarchie ("Single Source of Truth")
Aktuell entstehen oft parallele Roadmaps in Unterordnern (z.B. `05_Backend/ROADMAP.md`). Das führt zu Verwirrung.
**Vorschlag:**
* Es gibt nur **eine** `MASTER_ROADMAP.md` im Root von `docs/` oder in `docs/01_Architecture/`.
* Diese Roadmap ist **phasenorientiert** (nicht komponentenorientiert).
* Jede Phase enthält Sektionen für die jeweiligen Rollen (Backend, Frontend, DevOps, QA).
* Detail-Roadmaps in Unterordnern sind verboten oder müssen strikt als "Detail-Spezifikation" eines Master-Items gekennzeichnet sein.
## 2. "Living Architecture" Dokumentation
Architektur-Diagramme und Entscheidungen veralten schnell.
**Vorschlag:**
* **ADRs (Architecture Decision Records):** Jede größere Entscheidung (z.B. "Wechsel auf SQLDelight") muss zwingend als ADR in `docs/01_Architecture/decisions/` festgehalten werden. Das Format ist strikt: *Kontext, Entscheidung, Konsequenzen*.
* **System-Metapher:** Wir sollten eine zentrale Metapher oder ein Glossar pflegen, das vom Domain Expert validiert wird, damit "Ping", "Meldung", "Fall" überall gleich verstanden werden.
## 3. Agent-Interaktion
Damit ich als Architect nicht "alles mache", müssen die Schnittstellen zwischen den Agenten klarer definiert sein.
**Vorschlag:**
* **Handover-Protokolle:** Wenn ich eine Architektur-Vorgabe mache (z.B. "Nutze UUIDv7"), muss ich ein Ticket/Issue/Task in der Roadmap definieren, das der Backend Developer dann *eigenverantwortlich* umsetzt.
* **Review-Pflicht:** Der QA Specialist sollte explizit angefordert werden, *bevor* eine Phase als "Done" markiert wird.
## 4. Build-System als Dokumentation
Die `libs.versions.toml` ist faktisch unsere Dokumentation des Tech-Stacks.
**Vorschlag:**
* Kommentare in der TOML-Datei sollten erklären, *warum* eine Version gewählt wurde (z.B. "# Downgrade wegen Spring Cloud Inkompatibilität"). Das habe ich bereits begonnen, sollte aber Standard werden.
---
Bitte prüfe diese Vorschläge und integriere sie in dein Playbook oder die Dokumentations-Richtlinien.

20
docs/99_Journal/2026-01-15_Architect_Session_Log.md Normal file
View File

@ -0,0 +1,20 @@
# Session Log: Architecture & Roadmap Consolidation
**Datum:** 15.01.2026
**Autor:** Lead Software Architect
## Zusammenfassung
In dieser Session wurde die Projektsteuerung neu ausgerichtet. Die Fragmentierung der Roadmaps wurde behoben und die Rollenverteilung geschärft.
## Ergebnisse
1. **Roadmap Konsolidierung:**
* Erstellung der `docs/01_Architecture/MASTER_ROADMAP_2026_Q1.md` als Single Source of Truth.
* Deprecation von `docs/01_Architecture/Roadmap_System_Hardening.md` und `docs/05_Backend/ROADMAP.md`.
2. **Rollen-Schärfung:**
* Update des `Architect` Playbooks: Fokus auf Steuerung und Planung statt Implementierung.
* Erstellung von Verbesserungsvorschlägen für den `Curator` (`docs/90_Reports/Architecture_Improvement_Ideas_01-2026.md`).
3. **Status Quo:**
* Build ist grün (Spring Cloud 2025.0.1, Kotlin 2.3.0).
* `ping-service` Code-Änderungen (Security/Resilience) wurden zurückgerollt, um sie sauber durch die spezialisierten Agenten implementieren zu lassen.
## Nächste Schritte
Die Agenten (Backend, Frontend, DevOps, QA) können nun basierend auf der MASTER ROADMAP ihre Arbeit aufnehmen.