docs: add ADR-0022 for LAN-Sync protocol implementation

- Documented a hybrid "Event-Sourcing Light with Lamport Clocks" approach for offline-first LAN synchronization between Meldestelle and Richter-Turm.
- Included detailed options analysis (Event-Sourcing, CRDT, Timestamp-Sync) and rationale for the selected solution.
- Added specifications: SyncEvent model, Lamport clock rules, WebSocket protocol (handshake, sync, recovery), and domain mastership rules.
- Defined snapshot strategy to ensure scalable logs and efficient replay.
- Outlined implementation plan in four phases, highlighting task breakdown for backend and frontend teams.
- Updated architect, backend, and frontend roadmaps to reflect ADR-0022 integration steps.

Signed-off-by: Stefan Mogeritsch <stefan.mo.co@gmail.com>
This commit is contained in:
2026-04-03 09:44:09 +02:00
parent 236876a043
commit 2dd5453365
3 changed files with 394 additions and 1 deletions
@@ -0,0 +1,73 @@
# Session-Log: Architect B-1 — ADR-0022 LAN-Sync-Protokoll
> **Datum:** 3. April 2026
> **Agent:** 🏗️ Lead Architect
> **Aufgabe:** B-1 — ADR für LAN-Sync-Protokoll schreiben
---
## Erledigte Aufgaben
### 1. Optionen analysiert
Drei Synchronisationsstrategien wurden für den Kontext Meldestelle ↔ Richter-Turm bewertet:
| Option | Ergebnis |
|-----------------------------------------|--------------------------------------------------|
| A: Event-Sourcing (Append-Only Log) | Basis der gewählten Lösung (vereinfacht) |
| B: CRDT | Verworfen — zu komplex, keine KMP-Bibliotheken |
| C: Timestamp-Sync (Last-Write-Wins) | Verworfen — Uhren-Drift-Risiko, kein Audit-Trail |
| D: Event-Sourcing Light + Lamport-Uhren | **Gewählt** |
### 2. Entscheidung getroffen
**Event-Sourcing Light mit Lamport-Uhren** als LAN-Sync-Protokoll:
- Meldestelle = Master für Nennungen/Kassa; Richter-Turm = Master für Bewertungen/Ergebnisse
- Domänen-Mastership eliminiert strukturell ~90 % der Konflikte
- Lamport-Timestamps lösen verbleibende Konflikte deterministisch (kein Uhren-Drift)
- WebSocket-Transport (bidirektional), Handshake via HELLO/HELLO_ACK/SYNC_DELTA
- Snapshots alle 100 Events begrenzen Log-Größe und Replay-Zeit
### 3. ADR-0022 abgelegt
**Datei:** `docs/01_Architecture/adr/0022-lan-sync-protocol-de.md`
Inhalt:
- Vollständige Optionsanalyse (AD)
- `SyncEvent`-Datenmodell (Kotlin)
- Lamport-Uhr-Regeln
- WebSocket-Protokoll (Handshake, laufender Betrieb, Reconnect)
- Domänen-Mastership-Tabelle
- Snapshot-Strategie
- Implementierungsplan (4 Phasen)
- Offene Punkte (USB-Stick Fallback, Payload-Serialisierung, Multi-Richter-Turm)
### 4. Downstream-Teams informiert
- **👷 Backend Developer**: `Backend_Roadmap.md` — C-3 als freigegeben markiert, detaillierte Implementierungsschritte
ergänzt
- **🎨 Frontend Expert**: `Frontend_Roadmap.md` — C-3 als freigegeben markiert, WebSocket-Client- und UI-Aufgaben ergänzt
- **🏗️ Architect Roadmap**: Sprint B als abgeschlossen markiert
---
## Geänderte Dateien
| Datei | Änderung |
|----------------------------------------------------------------|------------------------------------------|
| `docs/01_Architecture/adr/0022-lan-sync-protocol-de.md` | **NEU** — ADR-0022 erstellt |
| `docs/04_Agents/Roadmaps/Architect_Roadmap.md` | Sprint B abgeschlossen, B-1 ✅ |
| `docs/04_Agents/Roadmaps/Backend_Roadmap.md` | C-3 freigegeben, Abhängigkeit ADR-0022 ✅ |
| `docs/04_Agents/Roadmaps/Frontend_Roadmap.md` | C-3 freigegeben, Abhängigkeit ADR-0022 ✅ |
| `docs/99_Journal/2026-04-03_Architect_B1_LAN-Sync_ADR-0022.md` | **NEU** — dieser Session-Log |
---
## Nächste Schritte
- **Sprint C-1** (Architect): Offline-First-Konzept für Desktop ↔ Backend ausarbeiten
- **Sprint C-3** (Backend): `SyncEvent`-Modell, SQLDelight-Tabellen, LamportClock, WebSocket-Server
- **Sprint C-3** (Frontend): WebSocket-Client, Sync-Status-UI, Discovery-UI
- **Offen**: USB-Stick Fallback — separate Besprechung (Sprint B/C)