chore(docs+infra): update roadmap, improve home server plan, and archive outdated reports

- Adjusted infrastructure roadmap to use VM instead of nested LXC for Docker hosting, enhancing isolation and compatibility.
- Clarified multi-architecture CI/CD setup with native ARM64 builds and QEMU-based x86_64 builds.
- Updated documentation to include backup and offline-first strategies.
- Archived outdated session logs and reports for better file organization.
This commit is contained in:
2026-02-06 20:49:47 +01:00
parent c8d19f7911
commit c51773a4c7
23 changed files with 41 additions and 28 deletions
@@ -0,0 +1,56 @@
---
type: Report
status: ARCHIVED
owner: Frontend Expert
date: 2026-01-17
tags: [frontend, kmp, auth, ping, architecture]
---
# 🚩 Statusbericht: Frontend (17. Jänner 2026)
**ARCHIVED:** This report reflects a past state. Please refer to `2026-01-23_Weekend_Status_Report.md` for the current status.
---
**Status:****Erfolgreich abgeschlossen**
Wir haben heute die technische Basis des Frontends massiv stabilisiert und das "Ping-Feature" als vollständige Referenz-Implementierung für gesicherte API-Kommunikation fertiggestellt.
### 🚀 Erreichte Meilensteine
1. **Central Authenticated Client:**
* Das `Ping-Feature` nutzt nun nicht mehr einen eigenen HttpClient, sondern den zentralen, via Koin bereitgestellten `apiClient`.
* Dieser Client injiziert automatisch den Bearer-Token aus dem `AuthTokenManager`.
* **Ergebnis:** Der "Secure Ping" funktioniert und validiert die gesamte Auth-Kette (Keycloak -> Token -> Request).
2. **Dependency Injection (Koin) Refactoring:**
* Saubere Trennung: `PingApiKoinClient` (neu) vs. `PingApiClient` (Legacy/Deprecated).
* Das `PingViewModel` erhält Abhängigkeiten nun strikt via Constructor Injection.
* Die Module (`pingFeatureModule`, `pingSyncFeatureModule`) werden in der Shell (`MainApp`/`main.kt`) korrekt geladen.
3. **Build-Pipeline & Web-Support (Critical Fix):**
* **Webpack Worker Fix:** Das Problem, dass `sqlite.worker.js` im Web-Build nicht gefunden wurde, ist behoben. Der Copy-Task in `build.gradle.kts` kopiert den Worker nun exakt in das von Kotlin/JS generierte Package-Verzeichnis.
* **Deprecations:** Veraltete Gradle-Konstrukte und Code-Deprecations wurden bereinigt.
4. **Qualitätssicherung:**
* Unit-Tests für den API-Client wurden auf `MockEngine` umgestellt und testen nun die neue Architektur.
---
# 📚 Curator Report (Documentation)
Als **Documentation & Knowledge Curator** habe ich die Erkenntnisse der heutigen Session gesichert:
1. **Neues Dokument:** [`docs/06_Frontend/feature-implementation-guide.md`](../../06_Frontend/feature-implementation-guide.md)
* Dient als "Blaupause" für alle zukünftigen Features.
* Beschreibt exakt, wie man den `AuthenticatedHttpClient` einbindet und die Koin-Module strukturiert.
* Dokumentiert den Web-Worker-Copy-Prozess für SQLDelight.
2. **Code-Dokumentation:**
* Veraltete Klassen wurden bereinigt oder dokumentiert.
* Die `build.gradle.kts` Files enthalten nun Kommentare zur Lösung des Webpack-Pfad-Problems.
---
**Nächste Schritte:**
Die technische "Vorlage" (Ping-Feature) ist nun sauber, performant und getestet. Die Infrastruktur (Auth, Sync, DB, Web-Build) steht. Wir sind bereit für die Implementierung der echten Fachdomänen (Veranstaltungen, Personen, Pferde).
@@ -0,0 +1,75 @@
---
type: Report
status: ARCHIVED
owner: Lead Architect
date: 2026-01-17
tags: [architecture, handover, critique, roadmap]
---
# 🏗️ Lead Architect Status Report & Handover
**ARCHIVED:** This report reflects a past state. Please refer to `2026-01-23_Weekend_Status_Report.md` for the current status.
---
**Datum:** 17. Jänner 2026
**Status:** 🟡 **PARTIALLY BLOCKED** (Frontend Architecture Split)
**Ziel:** Abschluss "Trace Bullet" (Ping Feature mit Auth, Sync & Tracing)
---
## 1. Executive Summary
Der technische Durchstich ist zu 85% erfolgreich.
***Backend & Infrastructure:** Exzellent. Zipkin läuft, Endpunkte (`/ping/sync`) sind deployt und sicher.
* ⚠️ **Frontend:** Kritischer Architektur-Bruch. Es existieren zwei parallele Implementierungen des `PingViewModel`. Die UI nutzt die alte Version (ohne Sync), während die neue Version (mit Sync) isoliert und ungenutzt ist.
---
## 2. Kritik & Prozessoptimierung (Collaboration Review)
Um solche "Split-Brain"-Situationen künftig zu vermeiden, ordne ich folgende Prozessänderungen an:
1. **Definition of Done (DoD) Schärfung:**
* Ein Feature gilt nicht als "Done", wenn der Code existiert, sondern erst, wenn er **in der `MainApp` verdrahtet** und für den User erreichbar ist.
* *Fehler heute:* Der Frontend Expert hat `PingEventRepository` und ein neues ViewModel gebaut, aber die UI (`PingScreen`) nicht darauf umgestellt.
2. **Architektur-Konsistenz (Single Source of Truth):**
* Wir haben aktuell Mischbetrieb zwischen `at.mocode.clients.*` (Legacy/Simple) und `at.mocode.ping.feature.*` (Clean Arch).
* *Entscheidung:* Wir migrieren schrittweise zu Clean Arch, aber **bestehende Features müssen funktional bleiben**. Keine "Ghost-Klassen" erstellen, die niemand aufruft.
3. **Cross-Functional Verification:**
* Der **Backend Developer** muss künftig verifizieren, ob seine neuen Endpunkte (z.B. `/ping/sync`) tatsächlich Traffic erhalten (via Zipkin/Logs), bevor das Ticket geschlossen wird.
---
## 3. Arbeitsaufträge (Chronologisch)
### A. @Frontend Expert (Priorität: HOCH)
**Aufgabe:** Behebung der ViewModel-Fragmentierung.
1. **Merge:** Integriere die Logik aus `at.mocode.ping.feature.presentation.PingViewModel` (Sync-Trigger) in das aktiv genutzte `at.mocode.clients.pingfeature.PingViewModel`.
2. **UI Integration:** Erweitere den `PingScreen` um einen "Sync Now"-Button oder eine Statusanzeige, die den `SyncManager` Status reflektiert.
3. **Cleanup:** Lösche das ungenutzte ViewModel in `at.mocode.ping.feature.presentation`, um Verwirrung zu vermeiden.
4. **Wiring:** Stelle sicher, dass das `PingEventRepositoryImpl` korrekt via Koin in das konsolidierte ViewModel injiziert wird.
### B. @Infrastructure & DevOps (Priorität: MITTEL)
**Aufgabe:** Verifizierung der Observability Kette.
1. Sobald das Frontend den Fix (A) geliefert hat: Prüfe im Zipkin UI (Port 9411), ob ein Trace sichtbar ist, der vom `web-app` Container über das `api-gateway` bis zum `ping-service` und zur DB reicht.
2. Falls Traces abbrechen: Prüfe die Header-Propagation (`b3` Header) im Ktor Client.
### C. @QA Specialist (Priorität: MITTEL)
**Aufgabe:** End-to-End Test "Offline Sync".
1. Szenario: App starten -> Login -> Daten laden -> Netzwerk trennen -> Daten ändern (wenn möglich) -> Netzwerk verbinden -> Sync prüfen.
2. Da wir aktuell nur "Read-Sync" (Server to Client) beim Ping haben: Prüfe, ob neue Pings vom Server nach Klick auf "Sync" in der lokalen DB landen.
### D. @Curator (Priorität: NIEDRIG)
**Aufgabe:** Dokumentation der Architektur-Entscheidung.
1. Aktualisiere `docs/01_Architecture/02_Frontend_Architecture.md`.
2. Dokumentiere den Beschluss: "Features werden sukzessive in Module (`features/`) ausgelagert. Während der Transition darf Code im `clients/`-Package verbleiben, muss aber die neuen Module nutzen (Dependency Injection)."
---
## 4. Abschluss
Der "Trace Bullet" ist technisch valide, scheitert aber auf den letzten Metern der Integration. Sobald der Frontend Expert den Merge vollzogen hat, ist Phase 1 des Projekts **Meldestelle** offiziell abgeschlossen.
**Lead Architect**
*End of Report*
@@ -0,0 +1,55 @@
---
type: Report
status: ARCHIVED
owner: Frontend Expert
date: 2026-01-19
tags: [frontend, refactoring, clean-architecture, ping-feature]
---
# 🚩 Statusbericht: Frontend Refactoring (19. Jänner 2026)
**ARCHIVED:** This report reflects a past state. Please refer to `2026-01-23_Weekend_Status_Report.md` for the current status.
---
**Status:****Erfolgreich abgeschlossen**
Wir haben die vom Lead Architect kritisierte Fragmentierung im Frontend behoben und das Ping-Feature auf eine saubere **Clean Architecture** migriert.
### 🎯 Erreichte Ziele (DoD)
1. **ViewModel-Fragmentierung behoben:**
* Die zwei parallelen `PingViewModel`-Implementierungen wurden konsolidiert.
* Das neue ViewModel (`at.mocode.ping.feature.presentation.PingViewModel`) vereint API-Calls und Sync-Logik.
* Das alte Package `at.mocode.clients.pingfeature` wurde **vollständig entfernt**.
2. **Clean Architecture Struktur:**
* Das Ping-Feature folgt nun strikt der neuen Struktur:
* `data`: `PingApiKoinClient`, `PingEventRepositoryImpl`
* `domain`: `PingSyncService` (neu eingeführt zur Entkopplung)
* `presentation`: `PingViewModel`, `PingScreen`
* `di`: `pingFeatureModule`
3. **UI Integration:**
* Der `PingScreen` wurde aktualisiert und enthält nun einen **"Sync Now"-Button** sowie eine Statusanzeige für den Sync-Vorgang.
4. **Test-Stabilität:**
* Die Unit-Tests (`PingViewModelTest`) wurden massiv verbessert.
* Wir nutzen nun **manuelle Fakes** (`FakePingSyncService`, `TestPingApiClient`) statt Mocking-Frameworks, um 100% JS-Kompatibilität zu gewährleisten.
* Race-Conditions in den Tests wurden durch korrekte Nutzung von `StandardTestDispatcher` und `advanceUntilIdle()` behoben.
* Namenskonflikte bei `Clock` wurden durch explizite Imports (`kotlin.time.Clock`) gelöst.
### 🛠️ Technische Details
* **Dependency Injection:** Das `pingFeatureModule` stellt alle Komponenten bereit und nutzt den zentralen `apiClient` aus dem Core.
* **Sync-Abstraktion:** Ein `PingSyncService` Interface wurde eingeführt, um das ViewModel vom generischen `SyncManager` zu entkoppeln. Dies erleichtert das Testen und zukünftige Erweiterungen.
* **Build:** Der Build ist **grün** (inkl. JS/Webpack und JVM Tests).
### 📝 Empfehlung für Folgemaßnahmen
* **Members & Auth Feature:** Diese sollten bei der nächsten Bearbeitung ebenfalls auf die neue Struktur (`at.mocode.{feature}.feature.*`) migriert werden.
* **Sync Up:** Aktuell testen wir nur "Sync Down" (Server -> Client). Für einen vollständigen Offline-Test sollte eine "Create Ping"-Funktion (Sync Up) ergänzt werden, sobald das Backend dies unterstützt.
---
**Fazit:** Das Ping-Feature ist nun die **"Goldene Vorlage"** für alle kommenden Features.
@@ -0,0 +1,65 @@
---
type: Report
status: ARCHIVED
owner: Lead Architect
date: 2026-01-19
tags: [architecture, review, frontend, ping-feature]
---
# 🏗️ Lead Architect Review: Frontend Refactoring
**ARCHIVED:** This report reflects a past state. Please refer to `2026-01-23_Weekend_Status_Report.md` for the current status.
---
**Datum:** 19. Jänner 2026
**Status:****APPROVED**
**Referenz:** `docs/90_Reports/2026-01-19_Frontend_Refactoring_Status.md`
---
## 1. Bewertung der Umsetzung
Ich habe die Änderungen des Frontend Experts geprüft und bin mit dem Ergebnis **sehr zufrieden**. Die kritisierten Punkte aus dem Handover vom 17.01. wurden präzise und vollständig adressiert.
### ✅ Architektur-Konsistenz
* **Clean Architecture:** Die Struktur unter `at.mocode.ping.feature` ist vorbildlich (`data`, `domain`, `presentation`, `di`).
* **Single Source of Truth:** Das Legacy-Package `at.mocode.clients.pingfeature` wurde restlos entfernt. Es gibt keine "Ghost-Klassen" mehr.
* **Entkopplung:** Die Einführung des `PingSyncService` Interfaces im Domain-Layer ist ein exzellenter Schachzug, um die UI vom generischen `SyncManager` zu isolieren.
### ✅ Integration (DoD erfüllt)
* **UI Wiring:** Die `MainApp.kt` importiert nun korrekt `at.mocode.ping.feature.presentation.PingScreen` und `PingViewModel`.
* **User Feedback:** Der `PingScreen` enthält nun den geforderten "Sync Now"-Button und zeigt das Ergebnis (`lastSyncResult`) an. Damit ist der Sync-Prozess für den User transparent.
### ✅ Code-Qualität
* **Koin Modul:** Das `pingFeatureModule` ist sauber definiert und nutzt `named("apiClient")` korrekt für den authentifizierten Zugriff.
* **JS-Kompatibilität:** Der explizite Einsatz von `kotlin.time.Clock` vermeidet bekannte Probleme im Multiplatform-Umfeld.
---
## 2. Arbeitsaufträge & Nächste Schritte
Da der "Trace Bullet" nun erfolgreich durchschlagen hat (Backend + Frontend + Sync + Auth), können wir die Entwicklung skalieren.
### A. @Frontend Expert (Priorität: MITTEL)
**Aufgabe:** Migration weiterer Features.
1. Wende das "Ping-Pattern" (Clean Arch) auf das `auth-feature` an.
2. Stelle sicher, dass auch dort ViewModels und Repositories sauber getrennt sind.
### B. @Backend Developer (Priorität: HOCH)
**Aufgabe:** Vorbereitung der Fachdomänen.
1. Beginne mit der Modellierung der **Veranstaltungen (Events)** Domain.
2. Erstelle die API-Contracts (`contracts` Modul) basierend auf den Anforderungen.
### C. @Infrastructure & DevOps (Priorität: NIEDRIG)
**Aufgabe:** Monitoring-Check.
1. Prüfe in den nächsten Tagen die Logs auf eventuelle Sync-Fehler, die durch die neue Frontend-Implementierung ausgelöst werden könnten.
---
## 3. Fazit
Der Architektur-Knoten ist gelöst. Das Projekt befindet sich nun auf einem stabilen Fundament für die weitere Skalierung.
**Lead Architect**
*End of Review*
@@ -0,0 +1,52 @@
---
type: Report
status: ARCHIVED
owner: Frontend Expert
date: 2026-01-20
tags: [frontend, backend, integration, ping-feature]
---
# 🚩 Statusbericht: Frontend-Backend Integration (20. Jänner 2026)
**ARCHIVED:** This report reflects a past state. Please refer to `2026-01-23_Weekend_Status_Report.md` for the current status.
---
**Status:****Erfolgreich verifiziert**
Wir haben die Integration zwischen dem KMP-Frontend (Desktop App) und dem Spring Boot Backend (via Gateway) erfolgreich getestet und stabilisiert.
### 🎯 Erreichte Meilensteine
1. **Infrastruktur-Verifikation:**
* Die gesamte Backend-Kette (Gateway -> Consul -> Ping-Service) läuft stabil in Docker.
* Das Gateway routet Anfragen korrekt an das Ping-Service.
2. **Security-Fix:**
* Der Endpunkt `/api/ping/simple` war fälschlicherweise geschützt (401).
* Er wurde in der Gateway-Konfiguration (`SecurityConfig.kt`) freigeschaltet und ist nun öffentlich erreichbar.
3. **End-to-End Kommunikation:**
* Die Desktop-App kann erfolgreich Requests an `http://localhost:8081/api/ping/simple` und `/health` senden.
* Die Authentifizierung (401 bei `/secure`) greift korrekt.
### 🔍 Testergebnisse (Desktop App)
| Endpunkt | Erwartet | Ergebnis | Status |
| :--- | :--- | :--- | :--- |
| `/api/ping/simple` | 200 OK | 200 OK | ✅ |
| `/api/ping/health` | 200 OK | 200 OK | ✅ |
| `/api/ping/public` | 200 OK | 200 OK | ✅ |
| `/api/ping/enhanced` | 200 OK | 401 Unauthorized | ⚠️ (Klären) |
| `/api/ping/secure` | 401 Unauthorized | 401 Unauthorized | ✅ |
| `/api/pings/sync` | 401 Unauthorized | 401 Unauthorized | ✅ |
### 📝 Nächste Schritte
1. **Auth-Feature:** Implementierung des Login-Flows im Frontend, um ein JWT zu erhalten.
2. **Authenticated Requests:** Nutzung des JWTs für Requests an `/secure` und `/sync`.
3. **Sync-Logik:** Finalisierung der Delta-Sync-Implementierung im Frontend.
---
**Fazit:** Die technische Basis für die Kommunikation steht. Der Weg ist frei für die Implementierung der Authentifizierung und der komplexeren Sync-Logik.
@@ -0,0 +1,50 @@
---
type: Report
status: DRAFT
owner: Frontend Expert
date: 2026-01-22
tags: [frontend, auth, refactoring]
---
# 🚩 Statusbericht: Frontend Authentifizierung & Refactoring
**Status:****Erfolgreich implementiert**
Wir haben die Authentifizierung im Frontend implementiert und dabei signifikante Verbesserungen an der Architektur vorgenommen.
### 🎯 Erreichte Meilensteine
1. **Architektur-Hygiene:**
* `auth-feature` ist nun `core-auth` (Infrastruktur statt Feature).
* Design-System Packages sind bereinigt.
* Klare Trennung von UI und Logik.
2. **Login-Flow (Desktop):**
* Login mit Username/Passwort funktioniert (`postman-client`).
* Token-Management (In-Memory) funktioniert.
* Logout funktioniert sauber.
3. **Backend-Integration:**
* `Secure Ping` und `Sync` Endpunkte sind mit Token erreichbar.
* 401/403 Fehler werden korrekt behandelt.
### 🔍 Testergebnisse
| Szenario | Erwartet | Ergebnis | Status |
| :--- | :--- | :--- | :--- |
| **Login (korrekt)** | 200 OK, Token erhalten | 200 OK | ✅ |
| **Login (falsch)** | 401 Unauthorized | 401 Unauthorized | ✅ |
| **Secure Ping (ohne Login)** | 401 Unauthorized | 401 Unauthorized | ✅ |
| **Secure Ping (mit Login)** | 200 OK | 200 OK | ✅ |
| **Sync (mit Login)** | 200 OK | 200 OK | ✅ |
| **Logout** | Token gelöscht, UI Reset | Funktioniert | ✅ |
### 📝 Nächste Schritte
1. **User-Info Parsing:** Korrektes Auslesen des Usernamens (`preferred_username`) aus dem Token.
2. **Web-Support:** Re-Aktivierung des PKCE Flows für die Web-Variante.
3. **Members Feature:** Implementierung der echten Fachlogik für Mitgliederverwaltung.
---
**Fazit:** Das Fundament steht. Die App ist sicher und kommuniziert erfolgreich mit dem Backend.
@@ -0,0 +1,49 @@
---
type: Report
status: FINAL
owner: Lead Architect
date: 2026-01-23
tags: [status, milestone, tracer-bullet]
---
# 🚀 Weekend Status Report: "Operation Tracer Bullet"
**Datum:** 23. Jänner 2026
**Phase:** Validierung & Härtung
## 1. Executive Summary
Das Projekt hat einen kritischen Meilenstein erreicht. Der "Tracer Bullet" (Ping-Service) durchdringt erfolgreich den gesamten Stack vom Frontend (Desktop) über das Gateway bis zur Datenbank, inklusive Security und Resilience.
Die technische Basis ist stabilisiert, die "Kinderkrankheiten" (Versionskonflikte, Docker-Networking) sind geheilt.
## 2. Status pro Gewerk
### 🏗️ Architecture & Build
* **Status:** 🟢 GRÜN
* **Erfolg:** Tech-Stack Stabilisierung (ADR-0013) hat Build-Probleme eliminiert.
* **Doku:** `AGENTS.md` definiert klare Zusammenarbeit.
### 🐧 Infrastructure (DevOps)
* **Status:** 🟢 GRÜN
* **Erfolg:** Docker-Environment ist vollständig operational.
* **Highlight:** Lösung des JWT-Validierungsproblems ("Split Horizon") ermöglicht saubere Auth in Containern.
### 👷 Backend (Spring Boot)
* **Status:** 🟢 GRÜN
* **Erfolg:** `ping-service` ist "Production Ready".
* Flyway Migrationen aktiv.
* CircuitBreaker & Metrics aktiv.
* Security (RBAC) aktiv.
### 🎨 Frontend (KMP)
* **Status:** 🟡 GELB (Teilweise fertig)
* **Erfolg:** Desktop-App kann sich einloggen und synchronisieren.
* **Offen:** Web-Support (PKCE Flow) muss nachgezogen werden.
* **UX:** Design ist noch rudimentär ("Developer Art").
## 3. Risiken & Blocker
* **Keine Blocker.** Der Weg für die fachliche Implementierung ist frei.
## 4. Plan für das Wochenende / Nächste Woche
1. **Web-Auth:** Frontend Expert implementiert PKCE für Browser-Support.
2. **Integration Test:** Einmaliger kompletter Durchstich (Frontend -> Backend -> DB) mit laufendem Docker-Stack.
3. **Domain Start:** Beginn der Arbeit an der `Events` (Veranstaltungen) Domäne.