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.
2026-02-06 20:49:47 +01:00
parent c8d19f7911
commit c51773a4c7
23 changed files with 41 additions and 28 deletions
@@ -0,0 +1,39 @@
+# Session Log: Frontend Integration & Backend Verification
+
+**Datum:** 20. Jänner 2026
+**Teilnehmer:** User, Frontend Developer (AI), Curator (AI)
+**Thema:** Verifizierung der Backend-Infrastruktur und Integration des Ping-Services.
+
+## Zusammenfassung
+In dieser Session wurde die Backend-Infrastruktur (Gateway, Consul, Ping-Service) erfolgreich getestet und das Routing im Gateway korrigiert. Anschließend wurde die Kommunikation zwischen der Desktop-App (Frontend) und dem Backend verifiziert.
+
+## Durchgeführte Arbeiten
+
+### 1. Backend-Analyse & Fixes
+*   **Analyse:** Das `ping-service` und die Gateway-Konfiguration wurden analysiert.
+*   **Problem:** Der Endpunkt `/api/ping/simple` lieferte `401 Unauthorized`, obwohl er öffentlich sein sollte.
+*   **Ursache:** Der Pfad `/api/ping/simple` fehlte in der Liste der `publicPaths` in der `GatewaySecurityProperties`.
+*   **Lösung:** `/api/ping/simple` wurde zur `SecurityConfig.kt` (via `GatewaySecurityProperties`) hinzugefügt.
+*   **Ergebnis:** Der Endpunkt ist nun öffentlich erreichbar.
+
+### 2. Infrastruktur-Test
+*   Die Docker-Container (Gateway, Consul, Keycloak, Ping-Service, Postgres, Redis, Zipkin) laufen stabil.
+*   **Routing-Test:**
+    *   `http://localhost:8081/api/ping/simple` -> **OK (200)**
+    *   `http://localhost:8081/api/ping/public` -> **OK (200)**
+    *   `http://localhost:8081/api/ping/health` -> **OK (200)**
+    *   `http://localhost:8081/api/ping/secure` -> **OK (401 Unauthorized - wie erwartet)**
+
+### 3. Frontend-Integration (Desktop App)
+*   Die Desktop-App wurde gestartet und hat erfolgreich Requests gegen das lokale Backend (via Gateway) ausgeführt.
+*   **Logs:**
+    *   `simple` & `health`: 200 OK.
+    *   `enhanced`, `secure`, `sync`: 401 Unauthorized (korrektes Verhalten für unauthentifizierte Requests).
+
+## Offene Punkte / Nächste Schritte
+1.  **Enhanced Ping:** Klären, ob `/api/ping/enhanced` öffentlich sein soll (aktuell 401).
+2.  **Authentifizierung:** Implementierung des Login-Flows im Frontend, um Zugriff auf geschützte Endpunkte (`/secure`, `/sync`) zu erhalten.
+3.  **Sync-Logik:** Implementierung der Delta-Sync-Logik im Frontend basierend auf den funktionierenden Endpunkten.
+
+## Dateien
+*   Geändert: `backend/infrastructure/gateway/src/main/kotlin/at/mocode/infrastructure/gateway/security/SecurityConfig.kt`
@@ -0,0 +1,46 @@
+---
+type: Journal
+status: COMPLETED
+owner: Curator
+date: 2026-01-20
+participants:
+  - Lead Architect
+  - Curator
+---
+
+# Session Log: Tech Stack Stabilisierung & Doku-Cleanup
+
+**Datum:** 20.01.2026
+**Ziel:** Stabilisierung des Builds (Versionskonflikte) und massive Bereinigung der Dokumentationsstruktur.
+
+## 1. Tech Stack Stabilisierung (ADR-0013)
+Aufgrund kritischer Inkompatibilitäten wurde der Tech-Stack angepasst (siehe `docs/01_Architecture/adr/0013-tech-stack-stabilization-2026.md`):
+*   **Spring Cloud:** Downgrade auf `2025.0.1` (Northfields) für Spring Boot 3.5.x Kompatibilität.
+*   **Compose Multiplatform:** Upgrade auf `1.10.0-rc02` für Kotlin 2.3.0 Kompatibilität.
+*   **Exposed:** Upgrade auf `1.0.0-rc-4`.
+*   **Micrometer:** Upgrade auf `1.16.1`.
+
+Die `gradle/libs.versions.toml` wurde entsprechend aktualisiert.
+
+## 2. Dokumentations-Hygiene
+Eine umfassende Aufräumaktion wurde durchgeführt, um die "Single Source of Truth" wiederherzustellen:
+
+### A. Archivierung
+*   Einführung von `_archive/` Unterordnern in `01_Architecture`, `05_Backend`, `90_Reports` und `99_Journal`.
+*   Veraltete Roadmaps, Reports und Logs wurden verschoben und mit dem Status `ARCHIVED` versehen.
+*   Originaldateien wurden durch "MOVED"-Hinweise ersetzt.
+
+### B. Prozess-Optimierung (Playbooks)
+*   **Curator:** Neue Rolle als "Quality Gatekeeper". Fordert nun aktiv ADRs und Handover-Artefakte ein.
+*   **Standard-Header:** Einführung von YAML-Frontmatter (`type`, `status`, `owner`) für alle Dokumente.
+*   **Master Roadmap:** `MASTER_ROADMAP_2026_Q1.md` ist die alleinige Quelle für die Planung.
+
+## 3. Ergebnis
+Das Projekt ist nun technisch (Build) und organisatorisch (Doku) wieder auf Kurs.
+*   Build-Konflikte sind gelöst.
+*   Veraltetes Wissen ist archiviert.
+*   Aktuelles Wissen ist klar markiert (`ACTIVE`).
+
+**Nächste Schritte:**
+*   Verifikation des "Trace Bullet" (DevOps/QA).
+*   Implementierung Frontend Auth (Frontend Expert).
@@ -0,0 +1,41 @@
+---
+type: Journal
+status: COMPLETED
+owner: Curator
+date: 2026-01-21
+participants:
+  - Backend Developer
+  - Lead Architect
+---
+
+# Session Log: 21. Jänner 2026
+
+## Zielsetzung
+Wissens-Transfer, Konsolidierung der Dokumentation und detaillierte Analyse der "Tracer Bullet" Architektur (Ping-Service & Infrastruktur).
+
+## Durchgeführte Arbeiten
+
+### 1. Infrastruktur & Status
+*   **Review:** Analyse der Docker-Compose Dateien (`dc-infra`, `dc-backend`, `dc-gui`, `dc-ops`) und Konfigurationen.
+*   **Report Update:** Aktualisierung des `Infrastructure_Status_Report_01-2026.md`. Bestätigung, dass die Infrastruktur Phase 1 (Hardening) und Phase 3 (Sync) erfolgreich unterstützt hat.
+*   **Anleitung:** Klärung des Start-Prozesses für das API-Gateway via Docker.
+
+### 2. Architektur-Diskussion (Deep Dive)
+*   **Ping-Service:** Definition als "Tracer Bullet" (Infrastruktur-Validierung, Blueprint, Offline-Lab).
+*   **Datenbank-Strategie:** Entscheidung für **PostgreSQL** (statt SQLite/Kafka) auch für den Ping-Service, um konsistente Patterns ("Database per Service") zu wahren.
+*   **Redis:** Bestätigung der Rolle als Cache und Infrastruktur-Store (Rate Limiting).
+*   **Security Flow:** Detaillierte Aufschlüsselung des OAuth2/OIDC Flows (Frontend -> Keycloak -> Gateway -> Service).
+
+### 3. Dokumentation (Single Source of Truth)
+*   **Neu:** Erstellung von `docs/05_Backend/Guides/Testing_with_Postman.md` als Anleitung für isolierte Backend-Tests.
+*   **Neu:** Erstellung von `docs/05_Backend/Services/PingService_Reference.md` als definitive Referenz für den Service.
+*   **Cleanup:** Archivierung veralteter Ping-Service Dokumentationen (`ping-service.md`, `PingService.md`).
+
+## Ergebnisse
+*   Das Verständnis über das Zusammenspiel der Komponenten (Docker, Auth, Service) ist vollständig synchronisiert.
+*   Die Dokumentation ist aufgeräumt und spiegelt den aktuellen technischen Stand wider.
+*   Eine klare Test-Strategie (Postman) für das Backend liegt vor.
+
+## Nächste Schritte
+*   **Backend:** Start der Modellierung der **Events Domain** (Veranstaltungen).
+*   **Frontend:** Implementierung des Login-Flows (basierend auf den Erkenntnissen dieser Session).
@@ -0,0 +1,44 @@
+---
+type: Journal
+status: COMPLETED
+owner: Curator
+date: 2026-01-22
+participants:
+  - DevOps & Infrastructure Engineer
+  - Owner (Stefan)
+---
+
+# Session Log: 22. Jänner 2026
+
+## Zielsetzung
+Analyse der Infrastruktur, Behebung von Authentifizierungs-Problemen (JWT/Keycloak) im Docker-Netzwerk und Validierung der "Tracer Bullet" Architektur (Ping-Service).
+
+## Durchgeführte Arbeiten
+
+### 1. Infrastruktur & IAM (Keycloak)
+*   **Analyse:** Diskrepanz zwischen Dokumentation (`Testing_with_Postman.md`) und Konfiguration (`meldestelle-realm.json`) festgestellt.
+*   **Fix (Realm):**
+    *   Neue Rolle `MELD_USER` als technischer Platzhalter für verifizierte Benutzer eingeführt.
+    *   Neuen Confidential Client `postman-client` erstellt, um saubere Backend-Tests via Password-Grant zu ermöglichen, ohne den Frontend-Client unsicher zu machen.
+    *   Dem User `admin` die Rolle `MELD_USER` zugewiesen.
+*   **Fix (Networking/JWT):**
+    *   Das "Split Horizon"-Problem identifiziert (Token Issuer `localhost` vs. Docker-interner Keycloak-Host).
+    *   `.env` Datei refactored: Trennung in `KC_ISSUER_URI` (Public) und `KC_JWK_SET_URI` (Internal).
+    *   `dc-backend.yaml` aktualisiert: `api-gateway` und `ping-service` nutzen nun diese expliziten Variablen.
+
+### 2. Dokumentation (Single Source of Truth)
+*   **Update:** `docs/05_Backend/Guides/Testing_with_Postman.md` an den neuen `postman-client` angepasst.
+*   **Neu:** `docs/07_Infrastructure/guides/jwt-in-docker.md` erstellt. Dieses Dokument erklärt das "Split Horizon"-Problem und dient als Referenz für Frontend- und Backend-Entwickler.
+
+### 3. Testing
+*   Erfolgreicher Durchlauf aller Postman-Tests (Connectivity, Health, Security Block, Auth Login, Security Access).
+*   Bestätigung, dass der `ping-service` nun korrekt Token validiert, die von außen (Postman) kommen, aber intern (Docker) geprüft werden.
+
+## Ergebnisse
+*   Die lokale Entwicklungsumgebung ist nun **vollständig funktionsfähig** und **auth-ready**.
+*   Die Infrastruktur-Konfiguration ist sauberer und expliziter (Trennung von Public/Internal URLs).
+*   Eine solide Basis für die Frontend-Login-Implementierung ist geschaffen.
+
+## Nächste Schritte
+*   **Frontend:** Implementierung des Login-Flows (Authorization Code Flow mit PKCE) unter Nutzung des `web-app` Clients.
+*   **Backend:** Beginn der Modellierung der **Events Domain** (Veranstaltungen).
@@ -0,0 +1,48 @@
+---
+type: Journal
+status: COMPLETED
+owner: Frontend Expert
+date: 2026-01-22
+participants:
+  - Frontend Expert
+  - User
+---
+
+# Session Log: Frontend Auth & Refactoring
+
+**Datum:** 22. Jänner 2026
+**Ziel:** Implementierung des Login-Flows im Frontend und Refactoring der Architektur.
+
+## Durchgeführte Arbeiten
+
+### 1. Architektur-Refactoring
+*   **Auth-Feature:** Das Modul `frontend/features/auth-feature` wurde nach `frontend/core/auth` verschoben, da es sich um eine Basisfunktionalität (Infrastruktur) handelt.
+*   **Design-System:** Das Package `at.mocode.clients.shared.commonui` wurde zu `at.mocode.frontend.core.designsystem` refactored.
+*   **Cleanup:** Alte, redundante Dateien und Module wurden bereinigt.
+
+### 2. Authentifizierung (Login)
+*   **Client:** Umstellung auf `postman-client` (Confidential Client) für den Desktop-Login, da `web-app` (Public Client) keine Direct Access Grants (Password Flow) unterstützte.
+*   **Secret:** Das Client Secret (`postman-secret-123`) wurde temporär in `AppConstants` hinterlegt (DEV-Only).
+*   **AuthApiClient:** Implementierung von Basic Auth Header für den Token-Request.
+*   **LoginViewModel:** Fix des State-Managements beim Logout (automatischer Reset von `isAuthenticated`).
+
+### 3. UI & Navigation
+*   **MainApp:** Einführung von `AppScaffold` und Scroll-Support für Landing/Welcome Screens.
+*   **Navigation:** Hinzufügen von "Zurück"-Buttons in `LoginScreen` und `PingScreen`.
+*   **Usability:** Entfernung verwirrender Browser-Login-Buttons.
+
+### 4. Backend-Integration
+*   **Secure Ping:** Erfolgreich getestet (200 OK mit Token).
+*   **Sync:** Erfolgreich getestet (200 OK mit Token). URL-Fix (`/api/pings/sync` -> `/api/ping/sync`).
+
+## Ergebnisse
+*   Die Desktop-App ist nun voll funktionsfähig: Login, Logout, Secure API Calls und Sync funktionieren.
+*   Die Code-Struktur ist sauberer und folgt der Trennung zwischen Core (Infra) und Features (Domain).
+
+## Offene Punkte
+*   **Browser-Login:** PKCE Flow für Web-Target muss noch sauber implementiert werden.
+*   **User-Info:** Das Profil zeigt noch "unbekannt", da der Username nicht korrekt aus dem Token geparst wird.
+*   **Secret Management:** Das Client Secret darf nicht im Code bleiben (für Prod).
+
+---
+**Status:** ✅ Erfolgreich abgeschlossen.
@@ -0,0 +1,42 @@
+---
+type: Journal
+status: COMPLETED
+owner: Curator
+date: 2026-01-23
+participants:
+  - Lead Architect
+  - Backend Developer
+  - Curator
+---
+
+# Session Log: 23. Jänner 2026
+
+## Zielsetzung
+Abschluss der "Tracer Bullet" Phase durch Härtung des Backends (Flyway) und Professionalisierung der Zusammenarbeit (Agent Protocol).
+
+## Durchgeführte Arbeiten
+
+### 1. Backend Hardening (Production Readiness)
+*   **Flyway:** Aktivierung von Flyway Migrationen für den `ping-service`.
+    *   `V1__init_ping.sql`: Schema-Definition.
+    *   `V2__seed_data.sql`: Initiale Testdaten für Sync-Tests.
+*   **Hibernate:** Umstellung von `ddl-auto` auf `validate`. Damit ist sichergestellt, dass die Anwendung nur startet, wenn das DB-Schema exakt zum Code passt.
+
+### 2. Agent Protocol & Organisation
+*   **AGENTS.md:** Definition eines strikten Protokolls für die Interaktion zwischen User und KI-Agenten.
+    *   Einführung von Badges (z.B. `🏗️ [Lead Architect]`) zur Kontext-Setzung.
+    *   Verlinkung aller Playbooks.
+*   **UI/UX Designer:** Einführung einer neuen Rolle für "High-Density Enterprise Design". Playbook erstellt.
+
+### 3. Dokumentation
+*   **Cleanup:** Aktualisierung der `docs/README.md` als zentraler Einstiegspunkt.
+*   **Status:** Erstellung des `docs/90_Reports/2026-01-23_Weekend_Status_Report.md`.
+
+## Ergebnisse
+*   Der `ping-service` ist nun technisch bereit für den produktiven Einsatz (kein `ddl-auto` mehr).
+*   Die Zusammenarbeit ist durch klare Rollen und Protokolle effizienter gestaltet.
+*   Der Status des Projekts ist "Grün" in allen Bereichen (außer Web-Auth, das für nächste Woche geplant ist).
+
+## Nächste Schritte (Montag)
+*   **Integration Test:** Vollständiger Durchstich (Frontend -> Gateway -> Service -> DB) mit dem gehärteten Stack.
+*   **Web Auth:** Implementierung PKCE Flow.
@@ -0,0 +1,39 @@
+---
+type: Journal
+status: COMPLETED
+owner: Curator
+date: 2026-01-23
+participants:
+  - DevOps Engineer
+  - Frontend Expert
+  - Curator
+---
+
+# Session Log: Auth & Build Fixes
+
+**Datum:** 23. Jänner 2026
+**Ziel:** Behebung von Build-Fehlern im Docker-Stack und Stabilisierung des Auth-Flows (Login/Logout) im Frontend.
+
+## Durchgeführte Arbeiten
+
+### 1. Docker Build Fix (DevOps)
+*   **Problem:** Der Build von `api-gateway` und `ping-service` schlug fehl, weil Gradle das Modul `:frontend:core:auth` konfigurieren wollte, dessen Pfad im Docker-Container fehlte.
+*   **Lösung:** Die `Dockerfile`s beider Services wurden aktualisiert, um die neue Frontend-Struktur (`frontend/core/auth` statt `frontend/features/auth-feature`) widerzuspiegeln.
+
+### 2. Frontend Auth Stabilisierung (Frontend Expert)
+*   **Problem 1 (Login 401):** Der `AuthApiClient` nutzte den globalen `apiClient`, der für das Gateway konfiguriert war (`DefaultRequest` mit Base URL). Dies führte zu Konflikten bei Requests gegen Keycloak.
+    *   **Lösung:** Einführung eines `baseHttpClient` (named) im `NetworkModule`, der "nackt" ist. Der `AuthApiClient` nutzt nun diesen Client.
+*   **Problem 2 (Logout ineffektiv):** Das Ktor `Auth` Plugin cachete den Token intern, sodass ein Logout (`AuthTokenManager.clearToken()`) erst beim Neustart wirksam wurde.
+    *   **Lösung:** Entfernung des `Auth` Plugins aus dem `apiClient`. Stattdessen wird der `Authorization` Header nun via `install(DefaultRequest)` dynamisch bei jedem Request aus dem `TokenProvider` gelesen.
+
+### 3. Keycloak Konfiguration
+*   **Problem:** Der Admin-User musste beim ersten Login das Passwort ändern (`temporary: true`), was den API-Login blockierte.
+*   **Lösung:** In `meldestelle-realm.json` wurde `temporary: false` gesetzt.
+
+## Ergebnisse
+*   Der Docker-Build läuft fehlerfrei durch.
+*   Login funktioniert stabil.
+*   Logout funktioniert sofort (nachfolgende Requests liefern korrekt 401).
+*   Die Architektur im Frontend ist durch die Trennung der HttpClients sauberer.
+
+**Status:** 🟢 **System Fully Operational**
@@ -0,0 +1,57 @@
+---
+type: Journal
+status: COMPLETED
+owner: Curator
+date: 2026-01-26
+participants:
+  - Lead Architect
+  - DevOps Engineer
+  - QA Specialist
+  - Curator
+---
+
+# Session Log: 26. Jänner 2026
+
+## Zielsetzung
+Stabilisierung der Web-Applikation (Wasm/JS) und Behebung von Datenbank-Initialisierungsfehlern (`WebWorkerException`) im Browser.
+
+## Durchgeführte Arbeiten
+
+### 1. Web-App Datenbank (SQLDelight & Wasm)
+*   **Problem:** Die Web-App startete nicht mit einer `WebWorkerException`. Ursache war, dass der Web Worker (`sqlite.worker.js`) und die zugehörige WASM-Datei (`sqlite3.wasm`) vom Browser nicht gefunden oder falsch geladen wurden.
+*   **Lösungsversuche:**
+    *   Aktivierung des Wasm-Targets (revertiert, da zu viele Folgefehler).
+    *   Anpassung der Gradle-Tasks (`copySqliteAssetsToWebpackSource`, `copySqliteAssetsToDist`), um Assets korrekt zu kopieren.
+    *   Anpassung des Workers (`sqlite.worker.js`) für manuelles Laden der WASM-Datei via `fetch`.
+    *   **Webpack-Hacks:** Umfangreiche Anpassungen in `webpack.config.d/ignore-sqlite-wasm.js`, um Webpack daran zu hindern, `sqlite3.wasm` als Modul zu parsen (was fehlschlug) und stattdessen auf ein `dummy.js` umzuleiten.
+*   **Aktueller Stand:**
+    *   Der Build schlägt noch fehl mit `export 'default' ... was not found`.
+    *   Die Strategie ist: Webpack sieht `dummy.js` (als Ersatz für `sqlite3.mjs` und `sqlite3.wasm`), während der Worker zur Laufzeit die echte `sqlite3.wasm` Datei manuell lädt.
+    *   `dummy.js` muss so angepasst werden, dass es einen korrekten Default-Export bereitstellt.
+
+### 2. Unit Tests (Ping Feature)
+*   **Problem:** `PingViewModelTest` schlug fehl, da Fehlerzustände nicht korrekt im UI-State gesetzt wurden.
+*   **Lösung:** `PingViewModel` angepasst, um `errorMessage` im State bei Exceptions korrekt zu setzen. Tests sind wieder grün.
+
+### 3. Gradle Build Optimierung
+*   **Problem:** Zirkuläre Abhängigkeiten zwischen Copy-Tasks und Webpack-Tasks.
+*   **Lösung:** Task-Reihenfolge in `build.gradle.kts` korrigiert (`mustRunAfter` statt `dependsOn` wo nötig).
+
+## Offene Punkte & Nächste Schritte
+
+1.  **Web-App Build Fix:**
+    *   `dummy.js` muss einen Default-Export (`export default function...`) bereitstellen, um den Import in `sqlite.worker.js` zu befriedigen.
+    *   Danach sollte der Webpack-Build durchlaufen.
+    *   Laufzeit-Test im Browser: Prüfen, ob der manuelle `fetch` im Worker funktioniert und die DB initialisiert wird.
+
+2.  **Wasm-Strategie:**
+    *   Langfristig sollte auf natives Wasm-Target umgestellt werden, sobald die Toolchain (Kotlin/Wasm + SQLDelight) stabiler ist. Aktuell ist der JS-Interop-Weg mit Webpack-Hacks notwendig.
+
+3.  **Integration Test:**
+    *   Sobald die Web-App läuft: Vollständiger Durchstich (Login -> Ping -> DB Sync) im Browser testen.
+
+## Technische Erkenntnisse
+*   **Webpack & Wasm:** Webpack 5 tut sich schwer mit dynamischen `require`-Aufrufen in Libraries wie `sqlite-wasm`, wenn diese nicht explizit als `externals` oder via `NormalModuleReplacementPlugin` behandelt werden.
+*   **SQLDelight im Browser:** Die Kombination aus OPFS (Origin Private File System), Web Workern und Wasm erfordert präzise Kontrolle über das Laden der Assets, die Webpack oft "wegabstrahieren" will.
+
+**Status:** 🟡 **Build Failing (Web)** / 🟢 **Tests Passing (JVM)**
@@ -0,0 +1,52 @@
+---
+type: Journal
+status: COMPLETED
+owner: Curator
+date: 2026-01-27
+participants:
+  - Lead Architect
+  - Frontend Expert
+  - Curator
+---
+
+# Session Log: 27. Jänner 2026
+
+## Zielsetzung
+Stabilisierung der Web-Applikation (JS/Wasm), Behebung von Build-Fehlern und Inbetriebnahme des Delta-Syncs.
+
+## Durchgeführte Arbeiten
+
+### 1. Web-App Build & Runtime Fixes
+*   **Problem:** Webpack-Build schlug fehl wegen `sqlite3.wasm` Handling.
+*   **Lösung:** Revertierung komplexer Webpack-Hacks. Der Build funktioniert nun standardmäßig, da die Abhängigkeiten korrekt konfiguriert sind.
+*   **Problem:** Login schlug fehl mit 404 auf `/members/sync`.
+*   **Lösung:** Veralteten Aufruf im `LoginViewModel` entfernt (Members-Modul existiert nicht mehr).
+
+### 2. SQLDelight Async Driver Issues (JS/Wasm)
+*   **Problem:** Laufzeitfehler `The driver used with SQLDelight is asynchronous, so SQLDelight should be configured for asynchronous usage` beim Aufruf von `getLatestSince` (Select).
+*   **Analyse:** Trotz `generateAsync = true` in `build.gradle.kts` scheint der generierte Code für `executeAsOneOrNull()` oder `executeAsList()` im Browser-Kontext Probleme zu machen, wenn er synchron aufgerufen wird (was bei `suspend` eigentlich nicht passieren sollte, aber evtl. durch fehlende Coroutine-Extensions im Classpath verursacht wurde).
+*   **Versuche:**
+    *   Transaktion entfernt/hinzugefügt -> Kein Effekt.
+    *   `executeAsList()` statt `executeAsOneOrNull()` -> Kein Effekt.
+    *   Explizites `await()` -> Kompilierfehler (da `upsert` bereits `suspend Unit` ist).
+    *   Hinzufügen von `libs.sqldelight.coroutines` zu `ping-feature` -> Kein Effekt auf den Laufzeitfehler.
+*   **Lösung (Workaround):** Bypass in `PingEventRepositoryImpl.getLatestSince()`. Die Methode gibt nun immer `null` zurück, was einen **Full-Sync** erzwingt.
+*   **Ergebnis:** Der Sync (`upsert`) läuft nun erfolgreich durch! Das Schreiben in die DB funktioniert asynchron und transaktional.
+
+### 3. UI/UX
+*   Das Ping-Service Dashboard zeigt nun im Event-Log erfolgreich "Sync completed successfully" an.
+
+## Offene Punkte & Nächste Schritte
+
+1.  **SQLDelight Async Select Fix:**
+    *   Tiefere Analyse, warum `select` Queries im JS-Target den Fehler werfen, während `insert` Queries funktionieren. Eventuell ein Bug in SQLDelight 2.0.2 in Kombination mit Kotlin 2.1.0 oder WebWorkerDriver Konfiguration.
+    *   Langfristig sollte der Bypass entfernt werden, um echten Delta-Sync zu ermöglichen.
+
+2.  **Daten-Visualisierung:**
+    *   Erweiterung des Dashboards um eine Ansicht der lokal gespeicherten Ping-Events, um den Sync auch visuell zu verifizieren (nicht nur via Logs).
+
+## Technische Erkenntnisse
+*   **SQLDelight & JS:** Die Kombination aus `generateAsync=true`, `WebWorkerDriver` und Multiplatform-Modulen ist fragil. Schreiboperationen (`suspend Unit`) scheinen robuster zu sein als Leseoperationen (`ExecutableQuery`), bei denen die asynchrone Ausführung explizit sichergestellt werden muss.
+*   **Tracer Bullet:** Der Ansatz, erst die Infrastruktur (Ping Service) komplett durchzustechen, hat sich bewährt. Wir haben fundamentale Probleme im Frontend-Stack (Wasm/DB) identifiziert und gelöst (bzw. mitigiert), bevor wir komplexe Fachlichkeit implementieren.
+
+**Status:** 🟢 **Web-App Running** / 🟡 **Sync (Full-Sync Workaround)**
@@ -0,0 +1,38 @@
+---
+type: Journal
+status: COMPLETED
+owner: Curator
+date: 2026-01-28
+participants:
+  - Lead Architect
+  - Frontend Expert
+---
+
+# Session Log: 28. Jänner 2026 - Lösung des SQLDelight-Sync-Problems
+
+## Zielsetzung
+Systematische Analyse und Behebung des kritischen SQLDelight-Bugs in der Web-App (JS/Wasm), der einen echten Delta-Sync verhinderte.
+
+## Durchgeführte Arbeiten
+
+### 1. Analyse & Fehlerreproduktion
+*   **Ausgangslage:** Der `PingEventRepositoryImpl` enthielt einen Workaround, der `getLatestSince()` immer `null` zurückgeben ließ, um einen Full-Sync zu erzwingen.
+*   **Reproduktion:** Der Workaround wurde entfernt und durch den ursprünglichen Code (`db.appDatabaseQueries.selectLatestPingEventId().executeAsOneOrNull()`) ersetzt.
+*   **Ergebnis:** Der Fehler `The driver used with SQLDelight is asynchronous...` wurde wie erwartet in der Browser-Konsole reproduziert.
+
+### 2. Systematische Ursachenforschung
+*   **Hypothese 1 (Konfiguration):** Die Build-Konfiguration (`frontend/core/local-db/build.gradle.kts`) wurde überprüft. `generateAsync.set(true)` war korrekt gesetzt. Die Fehlermeldung war also eine falsche Fährte.
+*   **Hypothese 2 (API-Nutzung):** Die Analyse ergab, dass `.executeAsOneOrNull()` eine **blockierende** API ist, die mit dem asynchronen Web-Worker-Treiber in Konflikt steht.
+*   **Lösung:** Die korrekte, **nicht-blockierende** API aus der SQLDelight-Coroutines-Erweiterung muss verwendet werden.
+
+### 3. Implementierung des Fixes
+*   Der Aufruf in `PingEventRepositoryImpl` wurde von `executeAsOneOrNull()` auf `awaitAsOneOrNull()` geändert.
+*   Der korrekte Import-Pfad `app.cash.sqldelight.async.coroutines.awaitAsOneOrNull` wurde hinzugefügt.
+
+## Ergebnis & Status
+*   **Erfolg:** Das SQLDelight-Sync-Problem ist **gelöst**.
+*   Die Web-App führt nun einen korrekten **Delta-Sync** durch, was durch den Aufruf des `/api/ping/sync?since=...` Endpunkts im Netzwerk-Log bestätigt wurde.
+*   Die wichtigste technische Schuld im Frontend wurde beseitigt.
+
+## Nächste Schritte (Diskutiert)
+*   **Docker-Integration:** Das Frontend (Build & Deployment) soll in die bestehende Docker-Konstruktion des Projekts integriert werden.
@@ -0,0 +1,48 @@
+---
+type: Journal
+status: COMPLETED
+owner: Curator
+date: 2026-01-29
+participants:
+  - Lead Architect
+  - DevOps Engineer
+  - Curator
+---
+
+# Session Log: 29. Jänner 2026 - Etablierung robuster Architektur-Guards mit ArchUnit
+
+## Zielsetzung
+Etablierung eines robusten, wartbaren und zentralisierten Systems zur Überprüfung und Erzwingung der Projekt-Architekturregeln, insbesondere der Trennung zwischen Modulen (Features, Services).
+
+## Durchgeführte Arbeiten
+
+### 1. Strategische Entscheidung
+*   **Problem:** Die Notwendigkeit, die modulare Trennung (z.B. zwischen Frontend-Features und Backend-Services) technisch zu erzwingen, wurde als kritisch für die Langlebigkeit des Projekts identifiziert.
+*   **Analyse:** Die bestehenden, skriptbasierten Gradle-Tasks (`archGuard...`) wurden als clever, aber fragil und nicht universell genug bewertet.
+*   **Entscheidung:** Es wurde beschlossen, auf **ArchUnit** als zentrales, typsicheres Werkzeug für die Architektur-Verifizierung zu migrieren.
+
+### 2. Implementierung (Iterativer Prozess & Fehlerbehebung)
+Die Implementierung war ein mehrstufiger Prozess, der mehrere Herausforderungen aufdeckte:
+
+1.  **Modul-Erstellung:** Ein neues Modul `:platform:architecture-tests` wurde erstellt und die ArchUnit-Abhängigkeiten (Version `1.4.1`) wurden im zentralen Versionskatalog `gradle/libs.versions.toml` deklariert.
+
+2.  **Abhängigkeits-Problem:** Der erste Versuch, die Abhängigkeiten dynamisch zu sammeln (`rootProject.subprojects.filter`), schlug fehl, da er versuchte, nicht-baubare Verzeichnis-Module (z.B. `:backend`) einzubinden.
+    *   **Lösung:** Umstellung auf eine explizite, manuelle Liste von `implementation(project(":..."))`-Abhängigkeiten in der `build.gradle.kts` des Test-Moduls.
+
+3.  **Klassen-Auffindungs-Problem:** Die ersten Test-Implementierungen schlugen mit der Meldung `Rule '...' failed to check any classes` fehl. Dies lag an einer Kombination aus falschen Paket-Mustern und einer inkorrekten Konfiguration des ArchUnit-Klassen-Imports.
+    *   **Lösung:** Die finale, robuste Lösung besteht darin, die `@AnalyzeClasses`-Annotation in den Testklassen zu verwenden und den `packages`-Parameter auf das Root-Package (`at.mocode`) zu setzen. Dies stellt sicher, dass ArchUnit den gesamten relevanten Classpath scannt, der von Gradle durch die expliziten Abhängigkeiten bereitgestellt wird.
+
+4.  **Syntax-Korrekturen:** Mehrere Iterationen waren nötig, um die korrekte Syntax für die ArchUnit-Regeln (insbesondere `slices().matching(...)` und die Paket-Identifier) zu finden.
+
+### 3. Finale Konfiguration
+
+*   **`build.gradle.kts` (`:platform:architecture-tests`):** Enthält eine explizite, manuell gepflegte Liste von Abhängigkeiten zu allen Modulen, die Code enthalten.
+*   **`FrontendArchitectureTest.kt`:** Verwendet `@AnalyzeClasses(packages = ["at.mocode.frontend"])` und die Regel `slices().matching("..frontend.features.(*)..").should().notDependOnEachOther()`.
+*   **`BackendArchitectureTest.kt`:** Verwendet `@AnalyzeClasses(packages = ["at.mocode.backend"])` und eine explizite `noClasses()..`-Regel, da die Backend-Services keine einheitliche Paketstruktur haben.
+*   **`README.md`:** Eine neue `README.md` wurde im Modul erstellt, um dessen Zweck und Verwendung zu dokumentieren.
+
+## Ergebnis & Status
+*   **BUILD SUCCESSFUL:** Die Architektur-Tests kompilieren und laufen erfolgreich durch.
+*   **Keine Verletzungen gefunden:** Die bestehende Codebasis ist sauber und verstößt nicht gegen die neu aufgestellten Regeln.
+*   Das Projekt verfügt nun über ein zentrales, robustes und erweiterbares System zur Durchsetzung von Architektur-Regeln, das in der CI-Pipeline ausgeführt wird.
+*   Die alten `archGuard`-Tasks wurden aus der Root-Build-Datei entfernt.
@@ -0,0 +1,41 @@
+---
+type: Journal
+status: COMPLETED
+owner: Lead Architect
+date: 2026-01-29
+participants:
+  - Lead Architect
+---
+
+# Session Log: 29. Jänner 2026 - Roadmap Update & Phase 4 Kickoff
+
+## Zielsetzung
+Aktualisierung der MASTER ROADMAP nach erfolgreichem Abschluss der "Tracer Bullet" Phase und Vorbereitung auf den Start der fachlichen Implementierung (Phase 4).
+
+## Durchgeführte Arbeiten
+
+### 1. Status-Review
+*   Der "Tracer Bullet" (Ping-Service) ist erfolgreich durch den gesamten Stack implementiert.
+*   Kritische technische Hürden (SQLDelight Async, Docker Networking, ArchUnit) sind genommen.
+*   Das Projekt ist bereit für die Skalierung auf echte Fach-Domänen.
+
+### 2. Roadmap Update
+*   **Phase 1-3:** Als "ABGESCHLOSSEN" markiert.
+*   **Phase 4 (Production Packaging & Domain Start):** Als "AKTUELL" definiert.
+*   **Neue Aufgaben:**
+    *   **DevOps:** Dockerisierung des Frontends.
+    *   **Backend:** Erstellung des `event-service`.
+    *   **Frontend:** Erstellung des `events`-Features.
+    *   **Architecture:** Sicherstellung der ArchUnit-Abdeckung für neue Module.
+
+### 3. Architecture Review Vorbereitung
+*   Die bestehenden ArchUnit-Tests (`BackendArchitectureTest`, `FrontendArchitectureTest`) wurden analysiert.
+*   **Erkenntnis:**
+    *   Backend-Tests erfordern manuelle Erweiterung der Package-Liste (`at.mocode.events..`).
+    *   Frontend-Tests erfordern strikte Einhaltung der Package-Struktur (`at.mocode.<domain>.feature`).
+*   Diese Anforderungen wurden explizit in die Roadmap-Tasks aufgenommen.
+
+## Ergebnis & Status
+*   Die Roadmap ist aktuell und spiegelt den Projektfortschritt wider.
+*   Die Aufgaben für die spezialisierten Agenten sind klar definiert.
+*   Der Fokus liegt nun auf der Erstellung der ersten echten Fachlichkeit ("Events").
@@ -0,0 +1,19 @@
+# Journal: Jänner 2026
+
+Dieses Dokument fasst die wichtigsten Ereignisse und Entscheidungen des Monats zusammen.
+
+## Woche 1-2: Initialisierung & Analyse
+*   **13.01.:** Start der Analyse. Identifikation von Strukturproblemen im Backend.
+*   **14.01.:** Konsolidierung der Dokumentationsstruktur.
+*   **15.01.:** Festlegung der "Docs-as-Code" Strategie und Agenten-Rollen.
+
+## Woche 3: "Tracer Bullet" (Ping Service)
+*   **17.01.:** Implementierung des Delta-Syncs im Backend (`/ping/sync`).
+*   **19.01.:** Frontend Refactoring auf Clean Architecture. Erfolgreicher Build.
+*   **20.01.:** Stabilisierung des Tech-Stacks (ADR-0013). Downgrade Spring Cloud, Upgrade Compose.
+*   **22.01.:** Frontend Auth Integration (Keycloak).
+*   **26.01.:** Web-App (JS/Wasm) Build Fixes (SQLite Wasm).
+*   **27.01.:** Web-App Sync Integration (Full-Sync Workaround für Async-Driver).
+
+---
+*Details siehe archivierte Session-Logs in `_archive/`.*