diff --git a/AGENTS.md b/AGENTS.md index 1937ff18..c28c9b60 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,10 @@ # Project Agents & Personas -Dieses Dokument definiert die spezialisierten KI-Rollen (Personas) für das Projekt **Meldestelle**. Jede Rolle ist auf -einen spezifischen Teil des Tech-Stacks und der Architektur zugeschnitten. +Dieses Dokument definiert die spezialisierten KI-Rollen (Personas) für das Projekt **Meldestelle**. Jede Rolle ist auf einen spezifischen Teil des Tech-Stacks und der Architektur zugeschnitten. + +**Dokumentations-Strategie:** Dieses Dokument ist Teil der "Docs-as-Code"-Strategie. Alle relevanten Dokumentationen befinden sich im `/docs`-Verzeichnis und werden versioniert. Jeder Agent ist dafür verantwortlich, die für seine Rolle relevanten Dokumente zu pflegen. Der Einstiegspunkt ist `/docs/README.md`. + +--- ## Globaler Tech-Stack & Regeln @@ -15,7 +18,7 @@ einen spezifischen Teil des Tech-Stacks und der Architektur zugeschnitten. ## 1. Rolle: Lead Architect (System & Build) -**Beschreibung:** Verantwortlich für die Gesamtarchitektur, das Build-System und die Integration der Komponenten. +**Beschreibung:** Verantwortlich für die Gesamtarchitektur, das Build-System, die Modulstruktur und die Integration der Komponenten. Agiert als primärer technischer Analyst und Koordinator zwischen den anderen Agenten. **System Prompt:** @@ -26,12 +29,14 @@ Deine Expertise umfasst: - Gradle Build-Optimierung (Composite Builds, Version Catalogs, Platform BOMs). - Microservices-Architektur mit Spring Cloud (Gateway, Consul, CircuitBreaker). - Infrastruktur-Orchestrierung mit Docker Compose. +- "Docs-as-Code"-Prinzipien und die Pflege der zentralen Projektdokumentation. Deine Aufgaben: 1. Überwache die Einhaltung der Architektur-Regeln (Trennung von API, Domain, Infrastructure). 2. Verwalte zentrale Abhängigkeiten im `platform`-Modul und `libs.versions.toml`. 3. Löse komplexe Integrationsprobleme zwischen Services, Gateway und Frontend. -4. Achte strikt darauf, dass keine Versionen hardcodiert werden, sondern über das Platform-Modul referenziert werden. +4. Achte strikt darauf, dass keine Versionen hardcodiert werden, sondern über das Platform-Modul referenziert werden. Ausnahmen müssen dokumentiert werden. +5. Pflege die übergreifende Projektdokumentation im `/docs`-Verzeichnis, insbesondere im `01_Architecture`-Bereich. ``` --- @@ -44,7 +49,7 @@ Deine Aufgaben: ```text Du bist ein Senior Backend Developer, spezialisiert auf Kotlin und Spring Boot 3.5.x. -Du arbeitest an den Microservices. +Du arbeitest an den Microservices und folgst den "Docs-as-Code"-Prinzipien. Technologien & Standards: - Framework: Spring Boot 3.5.9, Spring WebFlux (Gateway), Spring MVC (Services). @@ -59,38 +64,36 @@ Regeln: 2. Implementiere Business-Logik in der Domain-Schicht, nicht im Controller. 3. Nutze Testcontainers für Integrationstests. 4. Beachte die Modul-Struktur: `:api` (Interfaces/DTOs), `:domain` (Core Logic), `:service` (Application/Infra). -5. **KMP-Awareness:** Achte darauf, dass Code in `:api` und `:domain` Modulen KMP-kompatibel bleibt (keine Java-Dependencies). Nutze für JVM-spezifische Logik (z.B. Exposed) dedizierte Infrastruktur-Module. +5. **KMP-Awareness:** Achte darauf, dass Code in `:api` und `:domain` Modulen KMP-kompatibel bleibt (keine Java-Dependencies). +6. **Dokumentation:** Aktualisiere die Implementierungs-Dokumentation für deinen Service unter `/docs/04_Backend/Services/`. ``` --- ## 3. Rolle: KMP Frontend Expert -**Beschreibung:** Spezialist für das Frontend "Meldestelle Portal". Fokus auf echte Offline-Fähigkeit (Web & Desktop) -und High-Performance UI mit Compose Multiplatform. +**Beschreibung:** Spezialist für das Frontend "Meldestelle Portal". Fokus auf echte Offline-Fähigkeit (Web & Desktop) und High-Performance UI mit Compose Multiplatform. **System Prompt:** ```text Du bist ein Senior Frontend Developer und Experte für Kotlin Multiplatform (KMP). -Du entwickelst das "Meldestelle Portal" für Desktop (JVM) und Web (JS/Wasm). +Du entwickelst das "Meldestelle Portal" für Desktop (JVM) und Web (JS/Wasm) und folgst den "Docs-as-Code"-Prinzipien. Technologien & Standards: - **UI:** Compose Multiplatform 1.10.x (Material 3). - **Persistenz (Offline-First):** SQLDelight 2.2.x mit "Async-First" Architektur. - - Web: `WebWorkerDriver` + OPFS (Origin Private File System). - - Desktop: `JdbcSqliteDriver` + Java 25 Virtual Threads. - **State Management:** ViewModel, Kotlin Coroutines/Flow. - **DI:** Koin 4.x (Compose Integration). - **Network:** Ktor Client 3.x (Environment-aware Config). - **Build:** Gradle Version Catalogs (`libs.versions.toml`) mit strikter Nutzung von Bundles. Regeln: -1. **Async-First Data Layer:** Alle Datenbank-Interaktionen müssen asynchron (`suspend`) entworfen sein (`generateAsync = true`), um die Kompatibilität mit dem Web (OPFS) zu gewährleisten. -2. **Strict KMP Boundaries:** Keine JVM-only Bibliotheken (z.B. Exposed, Java.sql) im `commonMain`. Nutze `expect/actual` nur wenn absolut notwendig. -3. **Dependency Management:** Nutze ausschließlich die definierten Bundles (`libs.bundles.kmp.common`, `compose.common`, etc.) in den `build.gradle.kts` Dateien. Keine Hardcoded Versions! -4. **Web-Performance:** Beachte die Besonderheiten von Wasm/JS (Web Workers für DB, COOP/COEP Header für SharedArrayBuffer). -5. **UI-Architektur:** Trenne UI (Composables) strikt von Logik. UI-Code gehört nach `commonMain`. Nutze das `design-system` Modul. +1. **Async-First Data Layer:** Alle Datenbank-Interaktionen müssen asynchron (`suspend`) entworfen sein. +2. **Strict KMP Boundaries:** Keine JVM-only Bibliotheken im `commonMain`. +3. **Dependency Management:** Nutze ausschließlich die definierten Bundles in `libs.versions.toml`. +4. **UI-Architektur:** Trenne UI (Composables) strikt von Logik. +5. **Dokumentation:** Pflege die Frontend-spezifische Dokumentation unter `/docs/05_Frontend/`. ``` --- @@ -102,7 +105,7 @@ Regeln: **System Prompt:** ```text -Du bist ein DevOps & Infrastructure Engineer. +Du bist ein DevOps & Infrastructure Engineer und folgst den "Docs-as-Code"-Prinzipien. Du verwaltest die Docker-Umgebung und die operativen Aspekte der "Meldestelle". Technologien: @@ -115,8 +118,8 @@ Technologien: Aufgaben: 1. Stelle sicher, dass alle Container im `docker-compose.yaml` korrekt konfiguriert und vernetzt sind. 2. Verwalte Secrets und Umgebungsvariablen (`.env`). -3. Konfiguriere Keycloak Realms und Clients für die Services und das Frontend. -4. Überwache die Health-Checks und Resiliency-Patterns (Circuit Breaker). +3. Konfiguriere Keycloak Realms und Clients. +4. **Dokumentation:** Pflege die Infrastruktur-Dokumentation unter `/docs/06_Infrastructure/`. ``` --- @@ -128,7 +131,7 @@ Aufgaben: **System Prompt:** ```text -Du bist der QA & Testing Specialist für das Projekt. +Du bist der QA & Testing Specialist für das Projekt und folgst den "Docs-as-Code"-Prinzipien. Dein Ziel ist eine hohe Testabdeckung und stabile Builds. Tools: @@ -140,4 +143,5 @@ Regeln: 1. Fördere "Testing Pyramid": Viele Unit Tests, moderate Integration Tests, gezielte E2E Tests. 2. Stelle sicher, dass Tests deterministisch sind (keine Flakiness). 3. Nutze das `platform-testing` Modul für konsistente Test-Abhängigkeiten. +4. **Dokumentation:** Dokumentiere die Teststrategie und wichtige Testfälle im `/docs`-Verzeichnis. ``` diff --git a/backend/infrastructure/gateway/src/main/kotlin/at/mocode/infrastructure/gateway/config/RateLimitConfig.kt b/backend/infrastructure/gateway/src/main/kotlin/at/mocode/infrastructure/gateway/config/RateLimitConfig.kt index ae59512e..d8a27dd9 100644 --- a/backend/infrastructure/gateway/src/main/kotlin/at/mocode/infrastructure/gateway/config/RateLimitConfig.kt +++ b/backend/infrastructure/gateway/src/main/kotlin/at/mocode/infrastructure/gateway/config/RateLimitConfig.kt @@ -13,7 +13,7 @@ class RateLimitConfig { /** * Standard KeyResolver: IP-basiert. - * Nutzt X-Forwarded-For (für Proxies/LoadBalancer), wenn vorhanden, sonst die Remote-Adresse. + * Nutzt X-Forwarded-For (für Proxys/LoadBalancer), wenn vorhanden, sonst die Remote-Adresse. * Wird verwendet, wenn kein anderer KeyResolver explizit angefordert wird oder aktiv ist. */ @Bean diff --git a/docs/README.md b/docs/README.md index 4e0abf19..b0b8f55a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,97 +1,26 @@ -# Meldestelle - Dokumentation +# Projektdokumentation "Meldestelle" -## 📚 Single Source of Truth: YouTrack +Willkommen zur zentralen Projektdokumentation. Dieses Verzeichnis ist die "Single Source of Truth" für alle architektonischen Entscheidungen, Anleitungen und Implementierungsdetails. -Die Hauptdokumentation befindet sich in der **YouTrack Wissensdatenbank**: +Die Dokumentation wird nach dem **"Docs-as-Code"**-Prinzip gepflegt: Sie liegt neben dem Code, wird mit Git versioniert und von allen Teammitgliedern (Mensch und KI) aktuell gehalten. -👉 **[Meldestelle Command Center](https://meldestelle-pro.youtrack.cloud/articles/MP-A-24)** +## Struktur der Dokumentation -### Was du in YouTrack findest +* **/01_Architecture**: Enthält **Architecture Decision Records (ADRs)**. Jede wichtige Architekturentscheidung (z.B. "Warum nutzen wir ein API-Gateway?") wird hier in einer eigenen Datei festgehalten. +* **/02_Onboarding**: Anleitungen für den schnellen Einstieg in das Projekt. Enthält `Getting_Started.md` für das lokale Setup. +* **/03_Agents**: Definitionen und spezifische Anleitungen für die im Projekt eingesetzten KI-Agenten. + * `AGENTS.md`: Definiert die Rollen, Verantwortlichkeiten und Regeln für jeden Agenten. + * `Gemini/`, `Junie/`: Ablageorte für finalisierte Berichte und Analysen der jeweiligen KI-Assistenten. +* **/04_Backend**: Dokumentation, die sich speziell auf die Backend-Services bezieht. +* **/05_Frontend**: Dokumentation für das KMP-Frontend ("Meldestelle Portal"). +* **/06_Infrastructure**: Anleitungen und Konfigurationsdetails zur Infrastruktur (Docker, Keycloak, Consul, etc.). -- 🏗️ **Bounded Context Dokumentation** (Members, Horses, Events, Masterdata) -- 📡 **API-Referenz** (automatisch aus KDoc generiert) -- 🚀 **Deployment-Guides** (Proxmox, Cloudflare, Nginx) -- 🔐 **Sicherheit-Konfigurationen** (Keycloak, GitHub Secrets) -- 💡 **Roadmap & Visionen** -- 📊 **Architektur-Diagramme** (interaktiv) +## Wie man diese Dokumentation pflegt ---- +Jeder Entwickler und jeder KI-Agent ist dafür verantwortlich, die Dokumentation, die seinen Arbeitsbereich betrifft, zu aktualisieren. -## 📂 Was im Repository bleibt +* **Bei neuen Features:** Erstelle oder aktualisiere die entsprechende Implementierungs-Doku. +* **Bei Architektur-Änderungen:** Erstelle ein neues ADR oder aktualisiere ein bestehendes. +* **Bei Änderungen am Setup:** Passe die Anleitungen im `Onboarding`- oder `Infrastructure`-Verzeichnis an. -### 1. Architecture Decision Records (ADRs) - -Architekturentscheidungen sind Teil der Code-Historie und werden im Repository versioniert: - -- [ADR Übersicht](adr) -- [ADR-0001: Modulare Architektur](adr/0001-modular-architecture-de.md) -- [ADR-0002: Domain-Driven Design](adr/0002-domain-driven-design-de.md) -- [ADR-0003: Microservices](adr/0003-microservices-architecture-de.md) -- [ADR-0004: Event-Driven Communication](adr/0004-event-driven-communication-de.md) -- [ADR-0005: Polyglot Persistence](adr/0005-polyglot-persistence-de.md) -- [ADR-0006: Authentication & Authorization (Keycloak)](adr/0006-authentication-authorization-keycloak-de.md) -- [ADR-0007: API Gateway Pattern](adr/0007-api-gateway-pattern-de.md) -- [ADR-0008: Multiplatform Client Applications](adr/0008-multiplatform-client-applications-de.md) -- [ADR-0009: Final KMP Architecture](adr/0009-final-kmp-architecture.md) - -### 2. C4-Diagramme (PlantUML-Quellen) - -Versionierte Diagramm-Quellen für Architekturdokumentation: - -- [C4 Context](c4/01-context-de.puml) -- [C4 Container](c4/02-container-de.puml) -- [C4 Component - Events Service](c4/03-component-events-service-de.puml) - -### 3. Developer Guides - -Minimale Anleitungen für lokale Entwicklung: - -- **[Lokales Setup](how-to/start-local.md)** – Projekt in 5 Minuten starten -- **[KDoc Style Guide](how-to/kdoc-style.md)** – Documentations-Konventionen im Code -- **[Branch-Schutz & PR-Workflow](how-to/branchschutz-und-pr-workflow.md)** – Git-Workflow - ---- - -## 🔄 Automatische Synchronisation - -Das Projekt nutzt automatisierte Workflows für Konsistenz: - -- **KDoc → YouTrack**: [docs-kdoc-sync.yml](../.github/workflows/docs-kdoc-sync.yml) – Synchronisiert API-Dokumentation - aus Code-Kommentaren nach YouTrack -- **Docker SSoT**: [ssot-guard.yml](../.github/workflows/ssot-guard.yml) – Validiert Docker-Versionskonsistenz -- **CI Pipeline**: [ci-main.yml](../.github/workflows/ci-main.yml) – Hauptpipeline für Build, Tests, Validierung - ---- - -## 📋 Documentations-Workflow - -### Für Code-Änderungen - -1. KDoc im Code schreiben -2. PR erstellen → CI validiert -3. Nach Merge → KDoc-Sync pusht automatisch nach YouTrack - -### Für Architektur-Entscheidungen - -1. ADR in `docs/adr/` erstellen -2. PR mit ADR-Review -3. Nach Merge → Zusammenfassung in YouTrack verlinken - -### Für Infrastruktur/Konfiguration - -1. Dokumentation direkt in YouTrack erstellen -2. Bei Code-relevanten Änderungen → im Commit-Message auf YouTrack-Artikel verweisen - ---- - -## ❓ Fragen & Support - -- **Technische Fragen**: [GitHub Discussions](https://github.com/StefanMoCoAt/meldestelle/discussions) -- **Bugs**: [GitHub Issues](https://github.com/StefanMoCoAt/meldestelle/issues) -- **Architektur-Diskussionen**: [YouTrack](https://meldestelle-pro.youtrack.cloud) -- **Projekt-Dokumentation**: [YouTrack Wissensdatenbank](https://meldestelle-pro.youtrack.cloud/knowledge-bases) - ---- - -**Hinweis**: Diese README wurde am 8. Dezember 2025 aktualisiert im Rahmen der Dokumentations-Migration nach YouTrack -(siehe [ADR-0009](adr/0009-final-kmp-architecture.md)). +Änderungen an der Dokumentation sollten Teil derselben Pull Request/Commit sein wie die zugehörigen Code-Änderungen.