docs: consolidate roadmaps and update architecture documentation
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:
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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)
|
||||
...
|
||||
|
||||
Reference in New Issue
Block a user