diff --git a/backend/services/ping/ping-service/src/main/kotlin/at/mocode/ping/infrastructure/SecurityConfig.kt b/backend/services/ping/ping-service/src/main/kotlin/at/mocode/ping/infrastructure/SecurityConfig.kt new file mode 100644 index 00000000..65aa688c --- /dev/null +++ b/backend/services/ping/ping-service/src/main/kotlin/at/mocode/ping/infrastructure/SecurityConfig.kt @@ -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() + } +} diff --git a/core/core-utils/src/commonMain/kotlin/at/mocode/core/sync/Syncable.kt b/core/core-utils/src/commonMain/kotlin/at/mocode/core/sync/Syncable.kt new file mode 100644 index 00000000..65cc7464 --- /dev/null +++ b/core/core-utils/src/commonMain/kotlin/at/mocode/core/sync/Syncable.kt @@ -0,0 +1,9 @@ +package at.mocode.core.sync + +/** + * Interface for entities that can be synchronized. + */ +interface Syncable { + val id: String + val lastModified: Long +} diff --git a/docs/01_Architecture/MASTER_ROADMAP_2026_Q1.md b/docs/01_Architecture/MASTER_ROADMAP_2026_Q1.md new file mode 100644 index 00000000..c8ef0eda --- /dev/null +++ b/docs/01_Architecture/MASTER_ROADMAP_2026_Q1.md @@ -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. diff --git a/docs/01_Architecture/Roadmap_2026_Q1.md b/docs/01_Architecture/Roadmap_2026_Q1.md new file mode 100644 index 00000000..f76af24b --- /dev/null +++ b/docs/01_Architecture/Roadmap_2026_Q1.md @@ -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. diff --git a/docs/01_Architecture/Roadmap_System_Hardening.md b/docs/01_Architecture/Roadmap_System_Hardening.md index 51c31ce1..a28728a3 100644 --- a/docs/01_Architecture/Roadmap_System_Hardening.md +++ b/docs/01_Architecture/Roadmap_System_Hardening.md @@ -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) +... diff --git a/docs/04_Agents/Playbooks/Architect.md b/docs/04_Agents/Playbooks/Architect.md index 1718fe4d..79dab8cc 100644 --- a/docs/04_Agents/Playbooks/Architect.md +++ b/docs/04_Agents/Playbooks/Architect.md @@ -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. ``` diff --git a/docs/05_Backend/ROADMAP.md b/docs/05_Backend/ROADMAP.md index c4c48be7..73592016 100644 --- a/docs/05_Backend/ROADMAP.md +++ b/docs/05_Backend/ROADMAP.md @@ -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) +... diff --git a/docs/90_Reports/Architecture_Improvement_Ideas_01-2026.md b/docs/90_Reports/Architecture_Improvement_Ideas_01-2026.md new file mode 100644 index 00000000..af1b9fbb --- /dev/null +++ b/docs/90_Reports/Architecture_Improvement_Ideas_01-2026.md @@ -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. diff --git a/docs/99_Journal/2026-01-15_Architect_Session_Log.md b/docs/99_Journal/2026-01-15_Architect_Session_Log.md new file mode 100644 index 00000000..533fe1e2 --- /dev/null +++ b/docs/99_Journal/2026-01-15_Architect_Session_Log.md @@ -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.