mocode-software/meldestelle
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

chore: entferne veraltete Architekturdokumente

Browse Source 
Signed-off-by: StefanMoCoAt <stefan.mo.co@gmail.com>
This commit is contained in:
Stefan Mogeritsch
2026-05-05 21:22:46 +02:00
parent 6f15ada447
commit 15222b5453
258 changed files with 3388 additions and 6533 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/01_Architecture/Specifications/02_Frontend_Architecture.md
+89
View File
@@ -0,0 +1,89 @@
---
type: Reference
status: ACTIVE
owner: Lead Architect
last_update: 2026-03-15
---
# Frontend-Architektur & Modularisierungsstrategie
**Status:** ENTWURF
**Zuletzt aktualisiert:** 2026-01-19
**Kontext:** Migration zu Clean Architecture & Feature-Modulen
---
## 1. Übersicht
Die Frontend-Architektur von **Meldestelle** basiert auf **Kotlin Multiplatform (KMP)** mit **Compose Multiplatform**
für die Benutzeroberfläche. Wir folgen einem strikten **Clean Architecture**-Ansatz, um Testbarkeit, Skalierbarkeit und
Trennung der Zuständigkeiten sicherzustellen.
## 2. Modulstruktur
Das Projekt ist in folgende Schichten unterteilt:
### 2.1 Core-Module (`frontend/core`)
Wiederverwendbare Komponenten, die unabhängig von spezifischen Geschäftsfunktionen sind.
* `core-network`: Zentrale HTTP-Client-Konfiguration (Auth, Logging, ContentNegotiation).
* `core-sync`: Generische Synchronisierungslogik (`SyncManager`, `SyncableRepository`).
* `core-ui`: Gemeinsame UI-Komponenten und Design-System.
### 2.2 Feature-Module (`frontend/features`)
Jede Geschäftsdomäne (z.B. `ping`, `auth`, `events`) liegt in ihrem eigenen Modul.
Ein Feature-Modul MUSS die **Clean Architecture** Paketstruktur einhalten:
* `at.mocode.{feature}.feature.domain`
* **Entitäten:** Reine Datenklassen.
* **Interfaces:** Repository-Interfaces, Service-Interfaces.
* **Use Cases:** Geschäftslogik (optional, für komplexe Logik).
* `at.mocode.{feature}.feature.data`
* **Implementierungen:** Repository-Implementierungen, API-Clients.
* **DTOs:** Data Transfer Objects (wenn von Domain-Entitäten abweichend).
* `at.mocode.{feature}.feature.presentation`
* **ViewModels:** Zustandsverwaltung.
* **Screens:** Composable-Funktionen.
* `at.mocode.{feature}.feature.di`
* **Koin-Modul:** Konfiguration der Dependency Injection.
### 2.3 Shells (`frontend/shells`)
Anwendungs-Einstiegspunkte, die alles zusammenführen.
* `meldestelle-portal`: Die Haupt-Web-/Desktop-Anwendung.
## 3. Migrationsstrategie (Übergangsphase)
Wir migrieren aktuell von einer monolithischen `clients`-Paketstruktur zu modularen Feature-Modulen.
**Regeln für die Migration:**
1. **Neue Features:** Müssen direkt in `frontend/features/{name}` unter Verwendung der Clean Architecture-Struktur
implementiert werden.
2. **Bestehende Features:** Werden schrittweise migriert.
3. **Koexistenz:** Während des Übergangs ist Legacy-Code in `clients/` erlaubt, aber als veraltet markiert.
4. **Dependency Injection:** Legacy-Code muss die neuen Koin-Module verwenden, sofern verfügbar.
5. **Keine Ghost-Klassen:** Klassen nicht duplizieren. Wenn eine Klasse in ein Feature-Modul verschoben wird, muss die
alte in `clients/` gelöscht werden.
## 4. Wichtige Entscheidungen (ADRs)
### ADR-001: Entkopplung der Sync-Logik
* **Entscheidung:** ViewModels dürfen nicht direkt vom `SyncManager` abhängen.
* **Begründung:** Um einfacheres Testen zu ermöglichen und die Komplexität des generischen Sync-Mechanismus zu
verbergen.
* **Umsetzung:** Ein Domain-Service-Interface (z.B. `PingSyncService`) einführen, das den `SyncManager`-Aufruf kapselt.
### ADR-002: Feature-Modul-Isolation
* **Entscheidung:** Feature-Module sollten nach Möglichkeit nicht direkt voneinander abhängen.
* **Kommunikation:** Gemeinsame Core-Module oder lose Kopplung über Interfaces/Events verwenden, wenn modulübergreifende
Kommunikation nötig ist.
---
**Freigegeben von:** Lead Architect
docs/01_Architecture/Specifications/03_Build_System_Platform_Module.md
+71
View File
@@ -0,0 +1,71 @@
---
type: Reference
status: ACTIVE
owner: Lead Architect
---
# Architektur: Das Platform-Modul
## Überblick
Das **Platform-Modul** ist das Rückgrat der Build-Infrastruktur des Meldestelle-Projekts. Seine alleinige Aufgabe ist
die zentrale Verwaltung und Bereitstellung von Abhängigkeiten und deren Versionen. Dies stellt sicher, dass alle Module
im gesamten Projekt dieselben Bibliotheksversionen verwenden, was Inkonsistenzen ("JAR Hell") verhindert und die
Wartbarkeit drastisch verbessert.
Das Modul agiert als eine interne "Single Source of Truth" für alle externen Bibliotheken.
## Architektur
Das Platform-Modul ist in drei spezialisierte Untermodule aufgeteilt, die jeweils eine klare Aufgabe haben:
```text
platform/
├── platform-bom/ # Bill of Materials (BOM) - Erzwingt Versionen
├── platform-dependencies/ # Bündelt gemeinsame Laufzeit-Abhängigkeiten
└── platform-testing/ # Bündelt gemeinsame Test-Abhängigkeiten
```
### `platform-bom`
Dies ist das wichtigste Modul der Plattform. Es ist als "Bill of Materials" (BOM) konfiguriert und nutzt das
`java-platform`-Plugin von Gradle.
* **Zweck:** Definiert eine umfassende Liste von Abhängigkeiten und deren exakten, geprüften Versionen. Es importiert
auch andere wichtige BOMs (z.B. von Spring Boot und Kotlin).
* **Funktionsweise:** Andere Module importieren diese BOM mit `platform(projects.platform.platformBom)`. Gradle sorgt
dann dafür, dass alle transitiven und deklarierten Abhängigkeiten den in der BOM festgelegten Versionen entsprechen.
* **Vorteil:** Absolute Versionskontrolle über das gesamte Projekt.
### `platform-dependencies`
Ein einfaches "Sammelmodul", das die am häufigsten benötigten Laufzeit-Abhängigkeiten bündelt.
* **Zweck:** Vereinfacht die `build.gradle.kts`-Dateien der Service-Module. Anstatt 5-6 einzelne `kotlinx`- und
Logging-Bibliotheken hinzuzufügen, genügt eine einzige Abhängigkeit zu diesem Modul.
* **Verwendung:**
```kotlin
// In einem Service-Modul
dependencies {
implementation(projects.platform.platformDependencies)
}
```
### `platform-testing`
Analog zu `platform-dependencies`, aber speziell für Test-Bibliotheken.
* **Zweck:** Stellt ein konsistentes Set an Test-Frameworks (JUnit 5, MockK, AssertJ) und Werkzeugen (Testcontainers)
für alle Module bereit.
* **Verwendung:**
```kotlin
// In einem Service-Modul
dependencies {
testImplementation(projects.platform.platformTesting)
}
```
* **Optimierung:** Dieses Modul nutzt die in `libs.versions.toml` definierten `[bundles]`, um die Build-Datei extrem
kurz und lesbar zu halten.
docs/01_Architecture/Specifications/Meldestelle_Tech_Stack_Zusammenfassung.md
+362
View File
@@ -0,0 +1,362 @@
---
type: Reference
status: ACTIVE
owner: Lead Architect
date: 2026-03-07
---
# Meldestelle — Tech-Stack Zusammenfassung
> **Zweck:** Vollständige Referenz des eingesetzten Tech-Stacks im Projekt "Meldestelle".
> Dient als Basis für Recherchen zu Self-Hosted AI (Codegenerierung, RAG, Agenten).
> **Stand:** 07. März 2026
---
## 1. Überblick
Das Projekt "Meldestelle" ist eine **Kotlin-first, Cloud-native Microservices-Plattform** für die Verwaltung von
Reitsport-Meldungen (FEI / ÖTO). Es kombiniert ein **Kotlin Multiplatform (KMP) Frontend** mit einem **Spring Boot
Microservices Backend** auf einer vollständig self-hosted Infrastruktur.
```
┌─────────────────────────────────────────────────────────────────┐
│ Frontend (KMP) │ Backend (Spring Boot / Kotlin JVM) │
│ Kotlin 2.3 / Compose │ Java 25 / Spring Boot 3.5.9 │
│ JS + WASM (geplant) │ Microservices + API-Gateway │
├─────────────────────────────────────────────────────────────────┤
│ Infrastruktur (Self-Hosted auf Zora / Proxmox) │
│ Keycloak · Consul · Valkey · PostgreSQL · Zipkin │
│ Prometheus · Grafana · Caddy · Pangolin-Tunnel │
└─────────────────────────────────────────────────────────────────┘
```
---
## 2. Sprachen & Laufzeiten
| Komponente | Sprache / Runtime | Version |
|:-----------|:-----------------------|:--------|
| Backend | Kotlin (JVM) | 2.3.0 |
| Frontend | Kotlin (KMP / JS) | 2.3.0 |
| JVM | Java (Eclipse Temurin) | 25 (EA) |
| Build | Gradle (Kotlin DSL) | 9.3.1 |
| Plattform | ARM64 (AArch64) | Linux |
---
## 3. Frontend — Kotlin Multiplatform (KMP)
### 3.1 Core-Framework
| Bibliothek | Version | Zweck |
|:----------------------|:--------|:---------------------------------|
| Kotlin Multiplatform | 2.3.0 | Cross-Platform-Basis (JS + WASM) |
| Compose Multiplatform | 1.10.0 | UI-Framework (Deklarativ) |
| Compose Hot Reload | 1.0.0 | Live-Reload im Dev-Modus |
| Koin (DI) | 4.1.1 | Dependency Injection |
| Koin Compose | 4.1.1 | DI-Integration für Compose |
| Ktor Client | 3.4.0 | HTTP-Client (Multiplatform) |
| Kotlin Serialization | 2.3.0 | JSON-Serialisierung |
### 3.2 Persistenz (Offline-First)
| Bibliothek | Version | Zweck |
|:----------------|:--------|:-----------------------------|
| SQLDelight | 2.2.1 | Cross-Platform SQL-Datenbank |
| SQLite (WASM) | 3.51.1 | SQLite für Browser/WASM |
| SQLite (Native) | 2.6.2 | SQLite für JVM/Desktop |
### 3.3 Build-Targets
| Target | Status | Anmerkung |
|:--------------|:-----------|:--------------------------|
| KotlinJS | ✅ Aktiv | Primäres Build-Target |
| WASM | ⏳ Geplant | Warten auf Alpha-Version |
| Desktop (JVM) | ⚙️ Möglich | uiDesktop 1.7.0 vorhanden |
### 3.4 Modul-Struktur
```
frontend/
├── core/
│ ├── core-network/ # Ktor HTTP-Client, Auth-Interceptor
│ ├── core-ui/ # Design-System, Tokens, Komponenten
│ ├── core-domain/ # Shared Domain-Models
│ └── core-data/ # Repository-Interfaces
├── features/
│ ├── ping-feature/ # ✅ Blueprint: MVVM + Repository + DI + Tests
│ └── members-feature/ # ⏳ Auskommentiert (nächste Phase)
└── shells/
└── meldestelle-portal/ # Web-App Shell (Caddy-served)
```
---
## 4. Backend — Spring Boot Microservices
### 4.1 Core-Framework
| Bibliothek | Version | Zweck |
|:-------------------------|:---------|:---------------------------------|
| Spring Boot | 3.5.9 | Microservices-Framework |
| Spring Cloud | 2025.0.1 | Service Discovery, Config |
| Spring Security (OAuth2) | (Boot) | JWT-Validierung, Resource Server |
| Spring Data JPA | (Boot) | ORM-Layer |
| Spring Data Valkey | 0.2.0 | Cache-Integration (Valkey/Redis) |
| Spring WebFlux | (Boot) | Reaktive API (Gateway) |
| Kotlin Coroutines | 2.3.0 | Async/Non-blocking |
### 4.2 Persistenz
| Bibliothek | Version | Zweck |
|:--------------------|:--------|:----------------------|
| PostgreSQL Driver | 42.7.8 | JDBC-Treiber |
| Exposed (JetBrains) | 1.0.0 | Kotlin-native SQL DSL |
| Flyway | 11.19.1 | Datenbank-Migrationen |
| HikariCP | 7.0.2 | Connection Pool |
> **Strategie (ADR-001):** Hybrid — JPA für einfache CRUD-Entities, Exposed für komplexe Queries und Domain-Logik.
### 4.3 Caching & Messaging
| Bibliothek | Version | Zweck |
|:--------------|:--------|:--------------------------------|
| Lettuce | 6.6.0 | Valkey/Redis-Client (reaktiv) |
| Redisson | 4.0.0 | Distributed Locks, Pub/Sub |
| Caffeine | 3.2.3 | In-Memory Cache (L1) |
| Reactor Kafka | 1.3.23 | Kafka-Client (Phase 3 / Outbox) |
### 4.4 Observability & Tracing
| Bibliothek | Version | Zweck |
|:-------------------|:--------|:-----------------------------|
| Micrometer | 1.16.1 | Metriken (Prometheus-Export) |
| Micrometer Tracing | 1.6.1 | Distributed Tracing |
| Zipkin Reporter | 3.5.1 | Trace-Export zu Zipkin |
| Logback | 1.5.25 | Logging |
### 4.5 Security
| Bibliothek | Version | Zweck |
|:-----------------------|:--------|:-------------------------|
| Keycloak Admin Client | 26.0.7 | Keycloak-API-Integration |
| Spring Security OAuth2 | (Boot) | JWT Resource Server |
| Jackson (Kotlin) | 3.0.3 | JSON-Serialisierung |
### 4.6 API & Dokumentation
| Bibliothek | Version | Zweck |
|:-------------------|:--------|:-----------------------|
| Springdoc OpenAPI | 3.0.0 | Swagger / OpenAPI 3.1 |
| Jakarta Annotation | 3.0.0 | Jakarta EE Annotations |
### 4.7 Modul-Struktur
```
backend/
├── infrastructure/
│ ├── gateway/ # ✅ API-Gateway (Spring Cloud Gateway)
│ ├── security/ # ✅ Zentrales OAuth2/JWT-Modul (DRY)
│ ├── cache/
│ │ ├── cache-api/ # Interface-Abstraktion
│ │ └── valkey-impl/ # Valkey-Implementierung
│ ├── event-store/
│ │ ├── event-store-api/ # Interface-Abstraktion
│ │ └── valkey-impl/ # Valkey-Implementierung
│ ├── persistence/ # Hybrid JPA + Exposed
│ └── messaging/ # Kafka (Phase 3 / Outbox-Pattern)
└── services/
├── ping/ # ✅ Deployed — Test/Blueprint-Service
├── entries/ # ⚙️ Registriert, noch nicht deployed
├── events/ # 👻 Ghost Service (nicht registriert)
├── horses/ # 👻 Ghost Service (nicht registriert)
├── masterdata/ # 👻 Ghost Service (nicht registriert)
├── registry/ # 👻 Ghost Service (nicht registriert)
├── results/ # 👻 Ghost Service (nicht registriert)
└── scheduling/ # 👻 Ghost Service (nicht registriert)
```
---
## 5. Infrastruktur-Services (Docker)
### 5.1 Laufende Services
| Service | Image / Version | Port(s) | Zweck |
|:-------------|:-----------------------|:-----------|:----------------------------|
| PostgreSQL | postgres:16-alpine | 5432 | Primäre Datenbank |
| Keycloak | keycloak:26.4 (custom) | 8180, 9000 | IAM / OAuth2 / OIDC |
| Valkey | valkey:8-alpine | 6379 | Cache + Event-Store |
| Consul | consul:1.21 | 8500, 8600 | Service Discovery + Config |
| Zipkin | openzipkin/zipkin:3.5 | 9411 | Distributed Tracing |
| Prometheus | prom/prometheus:v3.4 | 9090 | Metriken-Sammlung |
| Grafana | grafana/grafana:11.6 | 3000 | Dashboards / Visualisierung |
| Caddy | caddy:2.10-alpine | 4000 | Web-App Serving (Frontend) |
| API-Gateway | (custom Spring Boot) | 8081 | Zentraler Eintrittspunkt |
| Ping-Service | (custom Spring Boot) | 8082 | Test/Blueprint-Service |
### 5.2 CI/CD & DevOps
| Tool | Version / Details | Zweck |
|:--------------|:---------------------|:------------------------------|
| Gitea | Self-Hosted (CT 101) | Git-Repository + Registry |
| Gitea Actions | (Runner VM 102) | CI/CD-Pipeline |
| Docker Buildx | ARM64 (linux/arm64) | Multi-Arch Image Build |
| Pangolin | Self-Hosted Tunnel | Reverse Proxy / Extern-Zugang |
### 5.3 Netzwerk & Routing
| Subdomain | Intern (Zora) | Zweck |
|:--------------------|:-----------------|:---------------|
| `git.mo-code.at` | `10.0.0.22:3000` | Gitea |
| `api.mo-code.at` | `10.0.0.50:8081` | API-Gateway |
| `auth.mo-code.at` | `10.0.0.50:8180` | Keycloak |
| `app.mo-code.at` | `10.0.0.50:4000` | Web-App |
| `photos.mo-code.at` | `10.0.0.24:2283` | Immich (Fotos) |
---
## 6. Code-Qualität & Build-Tools
| Tool | Version | Zweck |
|:-------------------|:--------|:---------------------------------|
| Detekt | 1.23.6 | Kotlin Static Analysis |
| ktlint | 12.1.1 | Kotlin Code Formatter |
| ArchUnit | 1.4.1 | Architektur-Tests (Layer-Regeln) |
| Dokka | 2.1.0 | API-Dokumentation (KDoc) |
| Ben-Manes Versions | 0.51.0 | Dependency-Update-Check |
| KSP | 2.3.4 | Kotlin Symbol Processing |
### Build-Konfiguration
```properties
# gradle.properties
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.workers.max=8
org.gradle.configuration-cache=false # wegen JS-Test Serialisierungsproblem
org.gradle.dependency.verification=strict
```
---
## 7. Test-Stack
| Bibliothek | Version | Zweck |
|:--------------------------|:--------|:-----------------------------|
| JUnit Jupiter | 5.11.3 | Unit-Tests |
| JUnit Platform | 1.11.3 | Test-Runner |
| MockK | 1.14.7 | Kotlin Mocking |
| AssertJ | 3.27.7 | Fluent Assertions |
| Testcontainers | 2.0.3 | Integration-Tests (Docker) |
| Testcontainers Keycloak | 4.0.1 | Keycloak-Integration-Tests |
| Testcontainers PostgreSQL | 1.21.4 | DB-Integration-Tests |
| Testcontainers Kafka | 1.21.4 | Kafka-Integration-Tests |
| ArchUnit | 1.4.1 | Architektur-Compliance-Tests |
---
## 8. Architektur-Prinzipien (ADRs)
| ADR | Entscheidung | Status |
|:-----|:--------------------------------------------------|:--------|
| 0001 | Modulare Architektur (DDD, Clean Architecture) | ✅ Aktiv |
| 0003 | Microservices-Architektur | ✅ Aktiv |
| 0004 | Event-Driven Communication (Kafka Phase 3) | ✅ Aktiv |
| 001 | Backend-Infrastruktur: Hybrid JPA+Exposed, Valkey | ✅ Aktiv |
| 0013 | Tech-Stack-Stabilisierung 2026 (Versionen) | ✅ Aktiv |
**Kern-Prinzipien:**
- **Offline-First:** SQLDelight als Cross-Platform-DB, Sync-Mechanismus
- **Docs-as-Code:** `/docs` als Single Source of Truth
- **DRY-Infrastruktur:** Shared Security/Cache/EventStore-Module
- **ARM64-Native:** Alle Images für `linux/arm64` gebaut
---
## 9. Relevanz für Self-Hosted AI
### 9.1 Welche AI-Aufgaben entstehen im Projekt?
| Aufgabe | Häufigkeit | Komplexität |
|:-----------------------------------|:-------------|:------------|
| Kotlin/Spring Boot Code-Completion | Täglich | Mittel |
| Compose Multiplatform UI-Code | Täglich | Mittel |
| SQL / Exposed DSL Queries | Häufig | Mittel |
| Gradle Kotlin DSL Build-Skripte | Gelegentlich | Niedrig |
| Docker / YAML Konfigurationen | Gelegentlich | Niedrig |
| Architektur-Entscheidungen (ADR) | Selten | Hoch |
| Fachlogik FEI/ÖTO Regelwerk | Selten | Sehr hoch |
### 9.2 Anforderungen an das AI-Modell
```
MUSS:
✅ Kotlin (JVM + Multiplatform) — sehr gute Unterstützung
✅ Spring Boot / Spring Cloud — sehr gute Unterstützung
✅ Compose Multiplatform — gute Unterstützung (neuere Modelle)
✅ SQL / PostgreSQL — sehr gute Unterstützung
✅ Docker / YAML — sehr gute Unterstützung
✅ Deutsch (Fachsprache Reitsport) — für RAG-Dokumente
NICE-TO-HAVE:
⭐ Gradle Kotlin DSL
⭐ Keycloak / OAuth2 / OIDC
⭐ Microservices-Architektur-Patterns
```
### 9.3 Empfohlene Modelle für diesen Stack
| Modell | Größe | Stärke | RAM-Bedarf |
|:------------------------|:------|:----------------------------------|:-----------|
| `qwen2.5-coder:14b` | 14B | Code (Kotlin, Java, SQL) — Top | ~10 GB |
| `deepseek-coder-v2:16b` | 16B | Code-Completion, Refactoring | ~12 GB |
| `llama3.1:8b` | 8B | Allgemein + Deutsch, schnell | ~6 GB |
| `qwen2.5:32b` | 32B | Architektur, Planung, Fachlogik | ~22 GB |
| `codellama:13b` | 13B | Code-Completion (IntelliJ-Plugin) | ~9 GB |
> **Empfehlung für Zora (64 GB RAM):**
> - **Primär:** `qwen2.5-coder:14b` — bester Kotlin/Spring-Support
> - **Sekundär:** `qwen2.5:32b` — für Architektur und Fachlogik
> - **IntelliJ-Integration:** `codellama:13b` oder `qwen2.5-coder:14b`
### 9.4 RAG-Dokumente (Priorität)
Folgende Projekt-Dokumente sind besonders wertvoll als RAG-Kontext:
```
Hohe Priorität:
├── docs/01_Architecture/MASTER_ROADMAP_2026_Q1.md
├── docs/01_Architecture/adr/ (alle ADRs)
├── docs/04_Agents/Playbooks/ (Agenten-Rollen)
├── gradle/libs.versions.toml (Versions-SSoT)
└── docs/07_Infrastructure/ (Infrastruktur-Referenz)
Mittlere Priorität:
├── docs/05_Backend/ (Backend-Guides)
├── docs/06_Frontend/ (Frontend-Guides)
└── docs/03_Domain/ (Fachlogik-Konzepte)
```
---
## 10. Zusammenfassung
```
TECH-STACK KOMPLEXITÄT
──────────────────────────────────────────────────────
Sprachen: Kotlin (JVM + KMP/JS)
Build: Gradle 9.3.1 + Kotlin DSL + libs.versions.toml
Frontend: Compose Multiplatform 1.10 + SQLDelight 2.2 + Koin 4.1
Backend: Spring Boot 3.5.9 + Spring Cloud 2025.0.1
Persistenz: PostgreSQL 16 + Exposed 1.0 + Flyway 11 + HikariCP 7
Cache: Valkey 8 + Lettuce 6.6 + Caffeine 3.2
Security: Keycloak 26.4 + Spring Security OAuth2 + JWT
Observability: Micrometer 1.16 + Zipkin 3.5 + Prometheus + Grafana 11.6
Service Mesh: Consul 1.21 + Spring Cloud Gateway
Messaging: Kafka (Phase 3) + Reactor Kafka 1.3
CI/CD: Gitea Actions + Docker Buildx (ARM64)
Hosting: Proxmox VE 8.4 + Docker Compose + Pangolin-Tunnel
```
docs/01_Architecture/Specifications/Onboarding-Backend.md
+68
View File
@@ -0,0 +1,68 @@
# Onboarding-Backend & Desktop-Identität
Dieses Dokument beschreibt die Backend-Infrastruktur für die Identifizierung und Authentifizierung von
Desktop-Clients ("Meldestelle-Biest").
## 🚀 Übersicht
Im Gegensatz zur Web-App (die via Keycloak/JWT authentifiziert) nutzen die Desktop-Instanzen für die
Offline-Synchronisation eine Identität, die während des **Onboarding-Prozesses** lokal vergeben und am Server
registriert wird.
## 🛡️ Authentifizierungs-Mechanismus
Die Authentifizierung erfolgt über zwei HTTP-Header, die bei jedem Request vom Desktop-Client mitgesendet werden müssen:
| Header | Beschreibung | Beispiel |
|:-----------------|:---------------------------------------------------|:-------------------|
| `X-Device-Name` | Der beim Onboarding vergebene Gerätename | `Meldestelle-PC-1` |
| `X-Security-Key` | Der beim Onboarding vergebene Sicherheitsschlüssel | `secret-key-123` |
### DeviceSecurityFilter
Ein Custom-Security-Filter (`DeviceSecurityFilter`) im Backend extrahiert diese Header und setzt einen Spring Security
Kontext mit der Authority `ROLE_DEVICE`.
## 🛰️ API-Endpunkte (Identity Service)
### 1. Gerät registrieren
Wird beim Abschluss des Onboarding-Screens aufgerufen.
- **URL:** `POST /api/v1/devices/register`
- **Body:**
```json
{
"name": "Meldestelle-PC-1",
"securityKeyHash": "...",
"role": "MASTER"
}
```
- **Hinweis:** Dieser Endpunkt ist `permitAll()`, um die Erstregistrierung zu ermöglichen.
### 2. Gerät abrufen
- **URL:** `GET /api/v1/devices/{name}`
- **Auth:** Erfordert `ROLE_DEVICE` oder `JWT`.
## 💾 Datenmodell (Exposed)
Die Tabelle `identity_devices` speichert die registrierten Instanzen:
- `id`: Eindeutige UUID.
- `name`: Gerätename (eindeutig).
- `security_key_hash`: Der Sicherheitsschlüssel (gehasht).
- `role`: `MASTER` oder `CLIENT`.
- `last_sync_at`: Zeitstempel der letzten erfolgreichen Synchronisation.
## 🛠️ Local Test-Setup
Für lokale Tests mit `curl`:
```bash
curl -X GET http://localhost:8081/api/v1/devices/Meldestelle-PC-1 \
-H "X-Device-Name: Meldestelle-PC-1" \
-H "X-Security-Key: secret-key-123"
```
docs/01_Architecture/Specifications/observability_dashboards.md
+62
View File
@@ -0,0 +1,62 @@
# Observability: Dashboards & Alerts
Dieses Dokument definiert die Monitoring-Strategie für das Masterdata-SCS gemäß der Roadmap.
## 1. Zentrale Dashboards
### 1.1 Import Performance Dashboard
*Fokus: Überwachung des ZNS-Ingestion-Workers.*
* **Import Duration:** Histogramm der Zeit pro Import-Datei (ASCII-Batch).
* **Records per Second:** Durchsatz der verarbeiteten Reiter/Pferde/Vereine während eines Imports.
* **Idempotency Skip Rate:** Anteil der übersprungenen Datensätze (bereits vorhanden/unverändert).
* **Validation Error Rate:** Anteil der Datensätze, die aufgrund von Validierungsfehlern abgelehnt wurden.
### 1.2 API Performance Dashboard
*Fokus: Ktor REST-Endpunkte (Lese-Kanal).*
* **Request Latency (P95/P99):** Latenz der GET-Endpunkte (Target: < 150ms).
* **Request Rate (RPS):** Anzahl der Anfragen pro Sekunde.
* **HTTP Error Rate (4xx/5xx):** Verteilung der Fehlercodes.
* **Active Connections:** Anzahl der parallelen Ktor/Netty Verbindungen.
### 1.3 Database Health Dashboard
*Fokus: Exposed/Postgres Persistenz.*
* **Connection Pool Usage:** Aktive vs. maximale Verbindungen.
* **Query Latency:** Dauer der SQL-Statements (Top 10 langsamste Queries).
* **Table Size Growth:** Wachstum der Core-Tabellen (`reiter`, `horse`).
* **Migration Status:** Flyway-Migrationsstatus und Schema-Version.
### 1.4 System Resources Dashboard
*Fokus: JVM & Infrastruktur.*
* **JVM Heap Usage:** Speicherverbrauch des Spring/Ktor Hybrid-Prozesses.
* **CPU Load:** CPU-Auslastung des Containers.
* **GC Pauses:** Dauer und Frequenz der Garbage Collection.
* **File Descriptors:** Auslastung der Datei-Handles (kritisch für Netty).
---
## 2. Alarm-Regeln (Alerts)
| ID | Alarm Name | Bedingung | Priorität |
|-------|-------------------------|--------------------------------------------------------|-----------|
| AL-01 | **API High Error Rate** | > 1% 5xx Fehler über 5 Minuten | Kritisch |
| AL-02 | **Slow API Requests** | P95 Latenz > 500ms für 2 Minuten | Warnung |
| AL-03 | **Import Failure** | Fehlerrate > 5% bei einem Batch-Lauf | Kritisch |
| AL-04 | **DB Pool Exhausted** | Pool-Auslastung > 90% für 1 Minute | Kritisch |
| AL-05 | **JVM OOM Risk** | Heap Usage > 85% nach Full GC | Kritisch |
| AL-06 | **Rule-Set Mismatch** | Mehrere aktive `RegulationConfig` Versionen pro Sparte | Warnung |
---
## 3. Implementierungs-Details
* **Metriken-Export:** Prometheus-Format via `/actuator/prometheus` (Port 8081).
* **Tracing:** Optional via Micrometer Tracing (Brave/Zipkin), falls global im Projekt aktiviert.
* **Logging:** Strukturiertes Logging via Logback (ISO8601, TraceContext).