docs: restructure domain documentation and update references
Implemented a standardized folder structure for domain documentation to improve clarity and maintainability. Migrated existing files to the new structure, updated links in related documentation, and added README files for navigation and guidance.
This commit is contained in:
@@ -0,0 +1,63 @@
|
||||
# Analyse und Strategie zur Wiederherstellung und Strukturverbesserung
|
||||
|
||||
**Datum:** 2026-01-02
|
||||
**Autor:** Junie
|
||||
**Kontext:** Dieser Bericht wurde nach einem großen Technologie-Upgrade (Kotlin 2.1.0+, Java 25, Spring Boot 3.5.x) erstellt, als die Infrastruktur und die Build-Prozesse instabil waren.
|
||||
|
||||
---
|
||||
|
||||
Es ist eine klassische Situation: Nach einem großen Technologie-Upgrade knirscht es oft an den Schnittstellen. Da der `ping-service` als technischer Blueprint dient, ist er der absolut richtige Startpunkt.
|
||||
|
||||
Hier ist der Schlachtplan, um Ordnung zu schaffen und die hexagonale Architektur sauber zu etablieren:
|
||||
|
||||
### 1. Wo beginnen? Bottom-Up vs. Top-Down
|
||||
Da die Infrastruktur aktuell nicht stabil läuft, wird ein **"Core-First"** Ansatz empfohlen, gefolgt vom **Backend-Durchstich**.
|
||||
|
||||
* **Zuerst: Core & Platform:** Ohne eine stabile Basis (`platform-bom`, `platform-dependencies`, `core-domain`) werden die anderen Module immer wieder Kompilierfehler werfen.
|
||||
* **Dann: Der technische vertikale Durchstich (`ping-service`):** Sobald die Plattform steht, wird der Weg repariert: `Infrastruktur (Docker) -> Ping-Service -> Gateway`.
|
||||
* **Zuletzt: Frontend:** Das Frontend (BFF-Gedanke) wird erst dann stabil, wenn die API-Contracts des Backends wieder verlässlich geliefert werden.
|
||||
|
||||
### 2. Ordnung schaffen: Der "Clean Desk" im Projekt
|
||||
Bevor Code gefixt wird, muss die Build-Umgebung aufgeräumt werden:
|
||||
|
||||
1. **Version Catalog Synchronität:** Die `libs.versions.toml` nutzt bereits Java 25 und Kotlin 2.1.0. Es muss geprüft werden, ob alle Gradle-Plugins (insbesondere das `compose-multiplatform` und `spring-boot` Plugin) mit Kotlin 2.1.0 kompatibel sind.
|
||||
2. **Modul-Konsolidierung (DDD):** Die "Modul-Explosion" sollte reduziert werden.
|
||||
* **Vorschlag:** Statt 5 Module pro Domain (`api`, `common`, `domain`, `infrastructure`, `service`), auf maximal zwei reduzieren:
|
||||
* `domain-api`: Nur DTOs und Interfaces (für KMP-Sharing mit dem Frontend).
|
||||
* `domain-service`: Die gesamte Implementierung (Hexagonal strukturiert in Packages).
|
||||
|
||||
### 3. Hexagonale Architektur im `ping-service` umsetzen
|
||||
Der `ping-service` ist aktuell noch sehr "Spring-lastig". Für eine echte hexagonale Vorlage sollte das Modul `ping-service` intern wie folgt umstrukturiert werden:
|
||||
|
||||
```text
|
||||
at.mocode.ping.service
|
||||
├── adapter
|
||||
│ ├── in
|
||||
│ │ └── web (PingController - Dein primärer Port-Adapter)
|
||||
│ └── out
|
||||
│ └── persistence (PingRepositoryAdapter - Sekundärer Port-Adapter)
|
||||
├── application
|
||||
│ ├── port
|
||||
│ │ ├── in (PingUseCase - Das Interface für den Controller)
|
||||
│ │ └── out (PingOutputPort - Interface für die Datenbank)
|
||||
│ └── service (PingService - Hier liegt die Business Logik, OHNE Spring-Annotationen wo möglich)
|
||||
└── domain
|
||||
└── model (PingEntity/Value Objects)
|
||||
```
|
||||
|
||||
### 4. Konkrete Schritte zur Reparatur
|
||||
|
||||
**Schritt 1: Infrastruktur-Check (Docker)**
|
||||
* Check `docker-compose.yaml`: Laufen Postgres und Keycloak?
|
||||
* `ping-service` application.yaml: Die Datenbank-Verbindung (JPA) aktivieren.
|
||||
|
||||
**Schritt 2: Backend API-Gateway Fix**
|
||||
* Die Security-Konfiguration (`SecurityConfig.kt`) wegen Bibliotheks-Änderungen in Spring Security 7/Spring Boot 3.5 prüfen.
|
||||
|
||||
**Schritt 3: Frontend (BFF) Anpassung**
|
||||
* Der `PingApiClient` im Frontend sollte gegen das **Gateway** (BFF-Pattern) laufen, nicht direkt gegen den Service.
|
||||
|
||||
### Empfehlung zur Vorgehensweise (Prioritäten):
|
||||
1. **Gradle-Build stabilisieren:** Alle `:platform:*` und `:core:*` Module müssen mit `./gradlew build` fehlerfrei durchlaufen.
|
||||
2. **Ping-SCS fertigstellen:** Eine minimale Datenbank-Speicherung im `ping-service` implementieren.
|
||||
3. **Gateway-Security:** Sicherstellen, dass das JWT von Keycloak korrekt zum `ping-service` durchgereicht wird.
|
||||
@@ -0,0 +1,46 @@
|
||||
# Plan zur Strukturierung der Domänen-Dokumentation
|
||||
|
||||
* **Datum:** 2026-01-14
|
||||
* **Autor:** Documentation & Knowledge Curator
|
||||
* **Status:** Entwurf
|
||||
|
||||
## Ausgangslage
|
||||
|
||||
Das Verzeichnis `docs/02_Domain` enthält wertvolle, aber zunehmend unübersichtliche Informationen.
|
||||
Es gibt eine Mischung aus:
|
||||
* Destilliertem Wissen (`01_Core_Entities.md`)
|
||||
* Referenz-Material (`Reference/FEI...`, `Reference/OETO...`)
|
||||
* Entwicklungs-Infos (`Development/`)
|
||||
* Implizitem Wissen (`Reference/Geschichten`)
|
||||
|
||||
## Zielbild
|
||||
|
||||
Gemäß **ADR-0012** (Proposed) soll eine strikte Trennung nach Reifegrad eingeführt werden.
|
||||
|
||||
## Migrations-Schritte
|
||||
|
||||
1. **Verzeichnisse erstellen:**
|
||||
* `docs/02_Domain/01_Core_Model/Entities`
|
||||
* `docs/02_Domain/01_Core_Model/Processes`
|
||||
* `docs/02_Domain/01_Core_Model/Rules`
|
||||
* `docs/02_Domain/03_Analysis/Scenarios`
|
||||
|
||||
2. **Dateien verschieben & umbenennen:**
|
||||
* `01_Core_Entities.md` -> `01_Core_Model/Entities/Overview.md` (oder aufsplitten)
|
||||
* `Reference/Geschichten` -> `03_Analysis/Scenarios`
|
||||
* `Reference/FEI_01-2026` -> `02_Reference/FEI_Regelwerk`
|
||||
* `Reference/OETO_01-2026` -> `02_Reference/OETO_Regelwerk`
|
||||
|
||||
3. **Development-Ordner auflösen:**
|
||||
* Die Inhalte von `docs/02_Domain/Development` (`kdoc-style.md`, `start-local.md`, `branchschutz...`) gehören **nicht** in die Domäne.
|
||||
* `start-local.md` -> `docs/02_Onboarding/`
|
||||
* `branchschutz...` -> `docs/02_Onboarding/`
|
||||
* `kdoc-style.md` -> `docs/02_Onboarding/CodingGuidelines/`
|
||||
|
||||
4. **Glossar anlegen:**
|
||||
* Erstellung von `docs/02_Domain/00_Glossary.md` als leere Hülle für den Start.
|
||||
|
||||
## Nächste Schritte für den User
|
||||
|
||||
* Bestätigung des ADR-0012.
|
||||
* Freigabe zur Durchführung der Datei-Operationen (Verschieben/Umbenennen).
|
||||
@@ -0,0 +1,53 @@
|
||||
# Projektanalyse Bericht: Meldestelle
|
||||
|
||||
* **Datum:** 2026-01-14
|
||||
* **Autor:** Documentation & Knowledge Curator
|
||||
* **Status:** Final
|
||||
|
||||
## 1. Einleitung
|
||||
|
||||
Dieser Bericht fasst die Ergebnisse einer vertieften Analyse des Projekts "Meldestelle" zusammen. Ziel war es, den aktuellen Stand der Architektur, der Infrastruktur und der Dokumentationspraxis zu bewerten. Die Analyse basiert auf dem aktuellen Dateisystemstand und den vorhandenen Dokumentationen.
|
||||
|
||||
## 2. Architektur & Technologie-Stack
|
||||
|
||||
Das Projekt präsentiert sich als modernes, verteiltes System mit einem hohen Anspruch an technologische Aktualität.
|
||||
|
||||
* **Backend:**
|
||||
* **Architektur:** Microservices-Ansatz mit Spring Boot 3.5.9 und Java 25/Kotlin 2.3.0.
|
||||
* **Struktur:** Klare Modulith-Struktur innerhalb der Services (`api`, `domain`, `infrastructure`, `service`), was Domain-Driven Design (DDD) fördert.
|
||||
* **Kommunikation:** Event-Driven Ansätze (Redis/Kafka angedeutet) und REST via Spring Cloud Gateway.
|
||||
* **Service Discovery:** HashiCorp Consul wird konsequent genutzt.
|
||||
|
||||
* **Frontend:**
|
||||
* **Technologie:** Kotlin Multiplatform (KMP) mit Compose Multiplatform 1.10.x.
|
||||
* **Plattformen:** Desktop (JVM) und Web (Wasm/JS).
|
||||
* **Offline-First:** Starke Betonung auf Offline-Fähigkeit mit SQLDelight und Sync-Strategien.
|
||||
|
||||
* **Build-System:**
|
||||
* Gradle 9.x mit Version Catalogs (`libs.versions.toml`) ist vorbildlich umgesetzt. Die Nutzung von Bundles reduziert Boilerplate in den Modulen.
|
||||
|
||||
## 3. Infrastruktur & Betrieb
|
||||
|
||||
Die Infrastruktur-Definition via Docker Compose ist umfassend und produktionsnah für eine lokale Umgebung.
|
||||
|
||||
* **Komponenten:** PostgreSQL, Redis, Keycloak, Consul, Prometheus, Grafana, Zipkin.
|
||||
* **Konfiguration:** Detaillierte Healthchecks, Netzwerk-Aliase und Profil-Nutzung (`infra`, `backend`, `gui`).
|
||||
* **Herausforderungen:** Die Komplexität der Orchestrierung zeigt sich in den jüngsten Journal-Einträgen (Startprobleme, Race Conditions beim Build).
|
||||
|
||||
## 4. Dokumentation (Docs-as-Code)
|
||||
|
||||
Die Dokumentationsstrategie ist exzellent definiert und wird sichtbar gelebt.
|
||||
|
||||
* **Struktur:** `docs/` als Single Source of Truth ist klar erkennbar.
|
||||
* **ADRs:** Vorhandene Architecture Decision Records (z.B. `ADR-001 Koin`, `ADR-002 SQLDelight`) belegen bewusste Entscheidungen.
|
||||
* **Rollen:** Die Definition von KI-Personas (Agents) im `docs/03_Agents/` Bereich ist innovativ und sorgt für konsistente Arbeitsweisen.
|
||||
* **Journal:** Die Nutzung des Journals (`docs/99_Journal/`) zur Fehlersuche und Statusverfolgung ist vorbildlich.
|
||||
|
||||
## 5. Aktuelle Beobachtungen & Risiken
|
||||
|
||||
* **Gateway-Konfiguration:** Es gibt ein offenes Problem mit dem `CircuitBreaker` im API-Gateway (siehe Journal vom 13.01.2026). Dies deutet auf eine fehlende Runtime-Dependency oder Fehlkonfiguration hin.
|
||||
* **Komplexität:** Der Tech-Stack ist sehr "bleeding edge" (Java 25, Kotlin 2.3, Spring Boot 3.5.9). Dies birgt das Risiko von Inkompatibilitäten und Tooling-Problemen (wie bereits bei den Gradle-Locks beobachtet).
|
||||
|
||||
## 6. Fazit
|
||||
|
||||
Das Projekt "Meldestelle" ist architektonisch sehr reif und modern. Die strikte Trennung von Belangen und die konsequente Anwendung von DDD und Docs-as-Code sind hervorzuheben. Der Fokus sollte kurzfristig auf der Stabilisierung der lokalen Docker-Umgebung liegen, um die Developer Experience (DX) sicherzustellen.
|
||||
Reference in New Issue
Block a user