diff --git a/README.md b/README.md index 0ff21449..584ed46c 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Meldestelle -> Modulares System für Pferdesportveranstaltungen — gebaut mit Domain-Driven Design, Kotlin Multiplatform und Microservices. +> Desktop‑First Meldestelle: Offline‑fähige Compose‑Desktop‑App mit optionalem Backend‑Stack. Domänengetrieben (DDD), Kotlin Multiplatform. [![CI/CD Pipeline](https://git.mo-code.at/mocode-software/meldestelle/actions/workflows/docker-publish.yaml/badge.svg)](https://git.mo-code.at/mocode-software/meldestelle/actions) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) @@ -15,20 +15,28 @@ Die gesamte Projektdokumentation (Architektur, Fachdomäne, Entwickler-Anleitung | Bereich | Inhalt | |-----------------------------------------------|---------------------------------------------| -| [01_Architecture](./docs/01_Architecture) | Master Roadmap, ADRs, C4-Modelle | +| [01_Architecture](./docs/01_Architecture) | Master Roadmap, ADRs, C4‑Modelle, Desktop‑Konzept | | [02_Guides](./docs/02_Guides) | Setup-Anleitungen, Entwickler-Guidelines | | [03_Domain](./docs/03_Domain) | Fachlichkeit, Turnierregeln, Entities | | [07_Infrastructure](./docs/07_Infrastructure) | Docker, Keycloak, CI/CD, Zora-Infrastruktur | +Wesentliche Architektur-Referenz: [Offline‑First Desktop & Backend (Kurzkonzept)](./docs/01_Architecture/konzept-offline-first-desktop-backend-de.md) + --- -## 🏗️ Tech Stack +## 🖥️ Primärer Fokus: Desktop‑App + +- Compose Multiplatform (JVM Desktop) als primäre Zielplattform +- Offline‑First: Lokale SQLDelight‑DB, Synchronisation optional +- Multi‑Tenant‑Backend optional für Sync/Verwaltung (Schema‑per‑Tenant, vgl. ADR‑0021) + +## 🏗️ Tech Stack (aktueller Stand) | Schicht | Technologie | |-----------------------|---------------------------------------------------| -| **Backend** | Kotlin, Spring Boot 3.x, Spring Cloud Gateway | -| **Frontend** | Kotlin Multiplatform (KMP), Compose Multiplatform | -| **Datenbank** | PostgreSQL + Exposed / JPA | +| **Frontend (primär)** | Kotlin Multiplatform (KMP), Compose Multiplatform | +| **Backend** | Kotlin (Ktor/Spring Boot), Spring Cloud Gateway | +| **Datenbank** | SQLDelight (lokal), PostgreSQL (Backend) | | **Auth** | Keycloak (OAuth2 / OIDC) | | **Cache** | Valkey | | **Service Discovery** | Consul | @@ -38,27 +46,51 @@ Die gesamte Projektdokumentation (Architektur, Fachdomäne, Entwickler-Anleitung --- -## 🚀 Quick Start (Lokal) +## 🚀 Quick Start (lokale Entwicklung) + +Empfohlen: Starte die Desktop‑App direkt aus dem Repo. Der Backend‑Stack ist optional und wird nur für Sync/Integration benötigt. + +### A) Desktop‑App starten (ohne Backend) + +Voraussetzungen: JDK 21+, aktuelle Gradle Wrapper verwendet. ```bash -# 1. Umgebungsvariablen vorbereiten (nur beim ersten Mal) -cp .env.example .env +# Desktop‑Shell ausführen (Compose Desktop) +./gradlew :frontend:shells:meldestelle-desktop:run +``` -# 2. Infrastruktur starten (Postgres, Keycloak, Valkey, Consul, Zipkin) +Hinweise: +- Beim ersten Start wird die lokale Datenbank initialisiert (Offline‑First). +- Architektur-Referenz: `docs/06_Frontend/MVVM_UDF_Pattern.md` (UDF/MVVM für ViewModels) + +### B) Optional: Backend‑Stack per Docker starten + +```bash +# 1. Umgebungsvariablen (nur beim ersten Mal) +cp .env.example .env || true + +# 2. Infrastruktur (Postgres, Keycloak, Valkey, Consul, Zipkin) docker compose -f docker-compose.yaml -f dc-infra.yaml up -d -# 3. Backend-Services starten (Gateway, Ping-Service) +# 3. Backend‑Services (Gateway, Masterdata, Ping, …) docker compose -f docker-compose.yaml -f dc-backend.yaml up -d -# 4. Ops-Stack starten (Prometheus, Grafana) +# 4. Ops‑Stack (Prometheus, Grafana) docker compose -f docker-compose.yaml -f dc-ops.yaml up -d -# 5. Optional: Web-App starten +# 5. Optional: Web‑Shell docker compose -f docker-compose.yaml -f dc-gui.yaml up -d ``` -> ⚠️ **Reihenfolge beachten:** Infra muss `healthy` sein, bevor Backend gestartet wird. -> Keycloak benötigt ~60–90 Sekunden zum Hochfahren. +> ⚠️ Reihenfolge beachten: Infra muss `healthy` sein, bevor Backend gestartet wird. Keycloak benötigt ~60–90 Sekunden. + +--- + +## 🧭 Legacy (V1) Hinweise + +- Ältere V1‑Abschnitte/Anleitungen (Web‑First/Microservices‑Only) gelten als DEPRECATED. +- Verwende für lokale Entwicklung primär die Desktop‑App (siehe Quick Start). Docker‑Stacks sind optional für Integration/Sync. +- In der Doku sind V1‑Seiten entsprechend markiert oder werden sukzessive bereinigt (siehe Roadmaps Sprint C‑4). ### Wichtige lokale Ports diff --git a/docs/02_Guides/start-local.md b/docs/02_Guides/start-local.md index 1f6666e1..934a87b6 100644 --- a/docs/02_Guides/start-local.md +++ b/docs/02_Guides/start-local.md @@ -7,14 +7,19 @@ tags: [setup, local, docker, gradle] # Start Local (Lokales Setup) -Kurzanleitung, um das Projekt lokal in wenigen Minuten zu starten. +Kurzanleitung, um das Projekt lokal in wenigen Minuten zu starten – Desktop‑First mit optionalem Docker‑Backend. -## Voraussetzungen -- Docker und Docker Compose (v2) -- Java 25 (JDK) -- Git +## Voraussetzungen (exakte Versionen) +- Git ≥ 2.40 +- JDK 25 (Temurin/Eclipse Adoptium empfohlen) – Projekttoolchain lädt bei Bedarf automatisch +- Gradle Wrapper 9.4.0 (wird über `./gradlew` automatisch verwendet) +- Docker Engine ≥ 24, Docker Compose v2 ≥ 2.24 -## Schnellstart +Hinweise: +- Die Java‑Toolchain wird per Gradle automatisch heruntergeladen (`org.gradle.java.installations.auto-download=true`). Ein lokal installiertes JDK 25 wird dennoch empfohlen für IDE‑Runs. +- Auf Apple‑Silicon (arm64) sind die Docker‑Images optimiert; Keycloak nutzt `start --optimized`. + +## Schnellstart (nur Backend in Docker) ```bash # 1) Repository klonen @@ -25,7 +30,7 @@ cd meldestelle # Kopiere die Vorlage. cp .env.example .env -# 3) Infrastruktur starten (Postgres, Redis, Keycloak, Monitoring, Gateway) +# 3) Infrastruktur starten (Postgres, Valkey, Keycloak, Tracing, Service Discovery) docker compose --profile infra up -d # 4) Backend starten (Gateway + Ping Service) @@ -33,10 +38,25 @@ docker compose --profile backend up -d ``` Sobald die Infrastruktur läuft, erreichst du unter anderem: -- Gateway: http://localhost:8081 -- Keycloak: http://localhost:8180 -- Grafana: http://localhost:3000 -- Prometheus: http://localhost:9090 +- Gateway (API): http://localhost:8081 +- Keycloak (IAM): http://localhost:8180 +- Zipkin (Tracing): http://localhost:9411 +- Consul (Service Discovery): http://localhost:8500 +- Optional Web‑App (falls `--profile gui` gebaut/gestartet): http://localhost:4000 + +## Desktop‑App starten (Compose Desktop) + +Die Desktop‑App ist der primäre Entwicklungs‑Entry‑Point. + +```bash +# 1) Abhängigkeiten bauen (optional; Gradle lädt automatisch beim ersten Run) +./gradlew :frontend:shells:meldestelle-desktop:build + +# 2) Desktop‑App starten +./gradlew :frontend:shells:meldestelle-desktop:run +``` + +Voraussetzung: Für Features, die Backend‑Konnektivität benötigen (z. B. Login, Stammdaten), muss das Docker‑Backend (infra + backend) laufen. Für rein lokale/offline Flows kann die App auch ohne Docker gestartet werden. ## Tests ausführen ```bash @@ -58,9 +78,12 @@ Sobald die Infrastruktur läuft, erreichst du unter anderem: docker compose down -v docker compose --profile infra up -d ``` -- Environment-Variablen: werden aus der `.env`-Datei im Root-Verzeichnis geladen. +- Environment‑Variablen: werden aus der `.env`‑Datei im Root‑Verzeichnis geladen. +- Gradle/Java Probleme? Stelle sicher, dass JDK 25 aktiv ist bzw. lasse die Gradle‑Toolchain das passende JDK laden. +- ARM64 (Apple Silicon): Falls Images nicht starten, lösche alte Images und starte neu: `docker compose down -v && docker system prune -af && docker compose --profile infra up -d`. ## Weiterführende Hinweise -- Architektur: `docs/01_Architecture/MASTER_ROADMAP_2026_Q1.md` +- README Quick‑Start (Desktop‑First): `README.md` +- Architektur‑Kurzkonzept (Offline‑First Desktop & Backend): `docs/01_Architecture/konzept-offline-first-desktop-backend-de.md` - ADRs: `docs/01_Architecture/adr/` - Aktuelle Reports: `docs/90_Reports/` diff --git a/docs/04_Agents/Roadmaps/Curator_Roadmap.md b/docs/04_Agents/Roadmaps/Curator_Roadmap.md index b6483608..19817253 100644 --- a/docs/04_Agents/Roadmaps/Curator_Roadmap.md +++ b/docs/04_Agents/Roadmaps/Curator_Roadmap.md @@ -57,14 +57,14 @@ ## 🟠 Sprint C — Priorität 2 (nächste Woche) - [ ] **C-1** | `README.md` aktualisieren - - [ ] Desktop-App als primären Fokus hervorheben - - [ ] Schnellstart-Anleitung für lokale Entwicklungsumgebung prüfen - - [ ] Veraltete V1-Abschnitte entfernen oder als deprecated markieren + - [x] Desktop-App als primären Fokus hervorheben → `README.md` (03.04.2026) + - [x] Schnellstart-Anleitung für lokale Entwicklungsumgebung prüfen → Desktop-Run (`:frontend:shells:meldestelle-desktop:run`) ergänzt (03.04.2026) + - [x] Veraltete V1-Abschnitte entfernen oder als deprecated markieren → Abschnitt „Legacy (V1) Hinweise“ in `README.md` (03.04.2026) -- [ ] **C-2** | Setup-Guide aktualisieren - - [ ] Schritt-für-Schritt: Projekt klonen → Docker starten → Desktop-App starten - - [ ] Voraussetzungen (JDK, Gradle, Docker) mit exakten Versionen dokumentieren - - [ ] Dokument in `docs/02_Guides/` ablegen +- [x] **C-2** | Setup-Guide aktualisieren ✅ *3. April 2026* + - [x] Schritt-für-Schritt: Projekt klonen → Docker starten → Desktop-App starten → `docs/02_Guides/start-local.md` + - [x] Voraussetzungen (JDK, Gradle, Docker) mit exakten Versionen dokumentiert (JDK 25, Gradle 9.4.0, Compose v2) + - [x] Dokument in `docs/02_Guides/` abgelegt/aktualisiert → `docs/02_Guides/start-local.md` - [ ] **C-3** | Unterordner-Struktur in `docs/` prüfen - [ ] Überladene Verzeichnisse identifizieren