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

docs: restructure domain documentation and update references

Browse Source 
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:
Stefan Mogeritsch
2026-01-15 13:44:49 +01:00
parent 7d71ca9a48
commit a454e6c97a
66 changed files with 881 additions and 693 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+19 -416
View File
@@ -1,438 +1,41 @@
# Meldestelle
> Modulares System für Pferdesportveranstaltungen mit Domain-Driven Design
> Modulares System für Pferdesportveranstaltungen mit Domain-Driven Design, Kotlin Multiplatform und Microservices.
[![CI Pipeline](https://github.com/StefanMoCoAt/meldestelle/workflows/CI%20-%20Main%20Pipeline/badge.svg)](https://github.com/StefanMoCoAt/meldestelle/actions)
[![Docker SSoT](https://github.com/StefanMoCoAt/meldestelle/workflows/Docker%20SSoT%20Guard/badge.svg)](https://github.com/StefanMoCoAt/meldestelle/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
---
## 📚 Dokumentation: Die einzige Quelle der Wahrheit
Die gesamte Projekt-Dokumentation – von der Architektur über die fachliche Domäne bis hin zu den Entwickler-Anleitungen – befindet sich im `/docs` Verzeichnis.
**Starte hier:**
### [**-> docs/README.md**](./docs/README.md)
---
## 🚀 Quick Start
```bash
# 1) Repository klonen
git clone https://github.com/StefanMoCoAt/meldestelle.git
cd meldestelle
# 2) Runtime-Environment vorbereiten (Single Source of Truth)
# Kopiere die Vorlage und passe sie bei Bedarf an.
cp -n .env.template config/env/.env 2>/dev/null || true
# Optionale lokale Geheimnisse/Overrides (gitignored):
# echo "POSTGRES_PASSWORD=meinlokalespasswort" >> config/env/.env.local
# 3) (Optional) Compose-Files generieren
# (nur falls du die Generator-Pipeline nutzt)
# DOCKER_SSOT_MODE=envless bash scripts/generate-compose-files.sh all development
# 4) Infrastruktur starten
docker compose -f docker-compose.yaml up -d
# 5) Services starten (Beispiel)
./gradlew :backend:services:results:results-service:bootRun
# oder – falls zentral gewollt und unterstützt
# ./gradlew bootRun
```
**Vollständige Anleitung**: [docs/02_Onboarding/Development/start-local.md](docs/02_Onboarding/Development/start-local.md)
---
## 📚 Dokumentation
### Single Source of Truth: YouTrack
Die Hauptdokumentation befindet sich in der **YouTrack Wissensdatenbank**:
👉 **[Meldestelle Command Center](https://meldestelle-pro.youtrack.cloud/articles/MP-A-24)**
#### In YouTrack
- 🏗️ **Bounded Context Dokumentation** (Members, Horses, Events, Masterdata)
- 📡 **API-Referenz** (automatisch aus KDoc generiert)
- 🚀 **Deployment-Guides** (Proxmox, Cloudflare, Nginx)
- 🔐 **Infrastruktur-Konfigurationen** (Netzwerk, Datenbanken, Keycloak)
- 💡 **Roadmap & Visionen**
#### Im Repository
- [📖 docs/README.md](docs/README.md) - Übersicht aller Repository-Dokumentation
- [🏛️ Architecture Decision Records](docs/01_Architecture/adr/)
- [📐 C4-Diagramme](docs/01_Architecture/c4/)
- [🛠️ Developer Guides](docs/02_Onboarding/Development/)
- [🤖 KI Operating Model](docs/03_Agents/)
- [🧰 Tooling/Guardrails](.junie/README.md)
---
## 🏗️ Architektur
### Bounded Contexts (DDD)
Das System ist in unabhängige Domänen aufgeteilt:
- **Members**: Mitgliederverwaltung
- **Horses**: Pferderegistrierung
- **Events**: Veranstaltungsverwaltung
- **Masterdata**: Stammdaten (Länder, Altersklassen, Turnierplätze)
### Technische Architektur
- **Microservices**: Unabhängige Services mit API Gateway
- **Event-Driven**: Apache Kafka für asynchrone Kommunikation
- **Polyglot Persistence**: PostgreSQL + Redis
- **Container-First**: Docker & Docker Compose
**Details**: [ADR-0002 Domain-Driven Design](docs/01_Architecture/adr/0002-domain-driven-design-de.md)
---
## ⚙️ Konfigurationsstruktur (Build vs. Runtime)
Laufzeit (Runtime) – Single Source of Truth:
- config/env/.env – globale Runtime-Werte (Ports, Hosts, Feature-Flags, Pfade, Profile)
- config/env/.env.local – lokale, geheime Overrides (gitignored)
- Optionale DDD-Slice-Overrides (nur wenn nötig):
- config/env/services/<service>.env (z. B. ping-service.env)
- config/env/infrastructure/<component>.env (z. B. api-gateway.env)
- config/env/clients/<client>.env (z. B. web-app.env)
Build-Zeit (nur Versionen/Tags/Pfade):
- docker/versions.toml – zentrale Versionsquelle (SSoT)
- docker/build-args/global.env – aus versions.toml abgeleitet (kann via scripts/generate-build-env.sh erzeugt werden)
- docker/build-args/{clients,infrastructure,services}.env – nur Build-relevante Pfade/Namen; keine Runtime-Variablen
Compose-Anbindung:
- Alle docker-compose*.yml laden config/env/.env und optional die per-Slice-Overrides via env_file
- Laufzeitwerte werden nicht via build.args eingeschleust
Deprecations / Umbenennungen:
- `DOCKER_*_VERSION` → `*_IMAGE_TAG` (nur Build-Zeit)
- `APP_VERSION` wurde vereinheitlicht als `VERSION`
Schnelltest / Smoke (lokal):
- docker compose -f docker-compose.yml up -d
- docker compose -f docker-compose.services.yml up -d
- docker compose -f docker-compose.clients.yml up -d
- Healthchecks prüfen: <http://localhost:3000> (Grafana), <http://localhost:9090> (Prometheus), <http://localhost:8180> (Keycloak), <http://localhost:8081> (Gateway), <http://localhost:4000> (Web)
Sicherheits-Hinweise:
- Keine echten Secrets im Repo; verwende config/env/.env.local für lokale Entwicklung
- Die optimierten Compose-Dateien (`*.optimized`) nutzen Docker-Secrets im Profil "prod"
---
## 🛠️ Tech Stack
| Komponente | Technologie | Version |
|----------------|-------------------------------|---------|
| **Backend** | Kotlin + Spring Boot | 3.x |
| **JVM** | Java | 25 |
| **Build** | Gradle | 9.2.1 |
| **Datenbank** | PostgreSQL | 16 |
| **Cache** | Redis | 7 |
| **Messaging** | Apache Kafka | 7.4.0 |
| **Auth** | Keycloak | 26.4.2 |
| **Monitoring** | Prometheus + Grafana + Zipkin | - |
| **Container** | Docker + Docker Compose | v2.0+ |
---
### 📦 Projektstruktur
```plaintext
Meldestelle/
├── backend/ # Backend: Gateway, Infrastruktur, Services
│ ├── infrastructure/
│ │ ├── cache/
│ │ ├── event-store/
│ │ ├── gateway/
│ │ ├── messaging/
│ │ └── monitoring/
│ └── services/
│ ├── entries/
│ ├── results/
│ ├── scheduling/
│ ├── ping/
│ └── registry/
├── frontend/ # Kotlin Multiplatform Frontend (Web/JVM)
│ ├── core/ # Shared Foundation
│ │ ├── design-system/
│ │ ├── domain/
│ │ ├── network/
│ │ ├── local-db/
│ │ └── navigation/
│ ├── features/ # Vertikale Slices
│ │ ├── auth-feature/
│ │ └── ping-feature/
│ ├── shared/
│ └── shells/
│ └── meldestelle-portal/
├── core/ # Gemeinsame Core-Module (JVM/KMP-unabhängig)
│ ├── core-domain/
│ └── core-utils/
├── docs/ # Repository-Dokumentation
│ ├── adr/ # Architecture Decision Records (flach)
│ ├── c4/ # C4-Diagramme (PlantUML)
│ ├── how-to/
│ └── reference/
├── platform/ # Versionen, BOM und Abhängigkeitsbündel
└── config/ # Runtime-/Tooling-Konfiguration
```
---
## 🔒 Docker Single Source of Truth (SSoT)
Alle Versionen zentral in **`docker/versions.toml`**:
### SSoT – Schnellstart (präzisiert)
Diese Befehle starten die Kern-Infrastruktur und die Services.
```bash
# Versionen anzeigen
bash scripts/docker-build.sh --versions
# 1. Umgebungsvariablen vorbereiten (nur beim ersten Mal)
cp .env.example .env
# Compose-Files generieren (Kompatibilitätsmodus)
bash scripts/generate-compose-files.sh all development
# Konsistenz validieren (Kompatibilitätsmodus)
bash scripts/validate-docker-consistency.sh all
# 2. Gesamtes System mit Docker Compose starten
docker compose up -d
```
### SSoT – Zwei Betriebsmodi (konsistent)
```bash
# 1) Kompatibilitätsmodus (compat)
bash scripts/docker-versions-update.sh sync
bash scripts/generate-compose-files.sh all development
bash scripts/validate-docker-consistency.sh all
# 2) Env-less Modus (empfohlen)
DOCKER_SSOT_MODE=envless bash scripts/docker-build.sh --versions
DOCKER_SSOT_MODE=envless bash scripts/generate-compose-files.sh all development
DOCKER_SSOT_MODE=envless bash scripts/validate-docker-consistency.sh all
```
Alternative (persistente Shell-Variante):
```bash
export DOCKER_SSOT_MODE=envless
bash scripts/docker-build.sh --versions
bash scripts/generate-compose-files.sh all development
bash scripts/validate-docker-consistency.sh all
```
#### CI-Schutz – lokal reproduzieren (getrennte/verkettete Befehle)
```bash
# Compat
bash scripts/docker-versions-update.sh sync && \
bash scripts/generate-compose-files.sh all development && \
bash scripts/validate-docker-consistency.sh all && \
git diff --name-only # sollte leer sein
# Env-less (Variante A: prefix)
DOCKER_SSOT_MODE=envless bash scripts/generate-compose-files.sh all development && \
DOCKER_SSOT_MODE=envless bash scripts/validate-docker-consistency.sh all && \
git diff --name-only # sollte leer sein
# Env-less (Variante B: export)
export DOCKER_SSOT_MODE=envless
bash scripts/generate-compose-files.sh all development && \
bash scripts/validate-docker-consistency.sh all && \
git diff --name-only # sollte leer sein
```
### Deployment (klarstellen, falls SSoT vorausgeht)
```bash
# Nur Infrastruktur
# Wenn eine handgeschriebene docker-compose.yaml existiert:
docker compose -f docker-compose.yaml up -d
# Falls Compose-Files generiert werden:
docker compose -f docker-compose.services.yaml up -d
# Services via Gradle
a) Einzeldienst
./gradlew :backend:services:results:results-service:bootRun
b) Falls unterstützt: alle (oder Aggregator)
./gradlew bootRun
```
**Details**: Siehe Abschnitt "Docker Single Source of Truth (SSoT)" weiter unten
---
## 🧪 Testing
### Unit Tests
```bash
./gradlew test
```
### Integration Tests
```bash
./gradlew integrationTest
```
### Spezifisches Modul testen
```bash
./gradlew :backend:services:results:results-service:test
```
---
## 🚢 Deployment
### Lokale Entwicklung
#### Nur Infrastruktur (Postgres, Redis, Kafka, Keycloak)
```bash
docker compose -f docker-compose.yaml up -d
```
#### Services über Gradle
```bash
./gradlew bootRun
```
---
## Docker Single Source of Truth (SSoT)—Details
Dieser Abschnitt beschreibt den lokalen Workflow für die zentrale Docker-Versionsverwaltung.
### TL;DR – Zwei Betriebsmodi
- **Kompatibilitätsmodus (Standard)**: `build-args/*.env` werden aus `versions.toml` generiert
```bash
bash scripts/docker-versions-update.sh sync
bash scripts/generate-compose-files.sh all development
bash scripts/validate-docker-consistency.sh all
```
- **Env-less Modus (Empfohlen)**: Keine `build-args/*.env` nötig – direkter Export aus `versions.toml`
```bash
DOCKER_SSOT_MODE=envless bash scripts/docker-build.sh --versions
DOCKER_SSOT_MODE=envless bash scripts/generate-compose-files.sh all development
DOCKER_SSOT_MODE=envless bash scripts/validate-docker-consistency.sh all
```
### Makefile-Befehle
Das Projekt verwendet ein umfassendes Makefile mit ~50 Befehlen für alle Development-Workflows:
```bash
make help # Zeigt alle verfügbaren Befehle
```
**Wichtigste Befehle:**
```bash
make full-up # Startet komplettes System (Infra + Services + Clients)
make services-up # Startet Backend (Infra + Microservices)
make dev-up # Startet Development-Environment
make test # Führt Integration-Tests aus
make health-check # Prüft System-Health
```
**SSoT-Befehle:**
```bash
make docker-sync # Synchronisiert versions.toml -> build-args/*.env
make docker-compose-gen # Generiert Docker Compose Files
make docker-validate # Validiert Docker SSoT Konsistenz
```
**Vollständige Referenz:** Siehe `Makefile` (`make help`) und `docs/02_Onboarding/Development/start-local.md`.
### Was ist die Single Source of Truth?
- **`docker/versions.toml`** enthält alle Versionsangaben (Gradle, Java, Node, Nginx, Postgres, Redis, etc.)
- **Env-less**: `docker/build-args/*.env` sind optional; Variablen zur Laufzeit aus `versions.toml`
- **docker-compose*.yml** werden generiert und referenzieren nur zentrale `DOCKER_*`-Variablen
- **Dockerfiles** deklarieren ARGs ohne Default-Werte
### Versionen ändern
```bash
bash scripts/docker-versions-update.sh update gradle 9.2.1
bash scripts/docker-versions-update.sh update node 22.21.0
bash scripts/docker-versions-update.sh update postgres 16-alpine
```
Danach: `generate` + `validate` ausführen!
### CI-Schutz
Die CI validiert Docker SSoT in beiden Modi (Matrix: compat + envless).
**Lokal reproduzieren**:
#### Compat
```bash
bash scripts/docker-versions-update.sh sync && \
bash scripts/generate-compose-files.sh all development && \
bash scripts/validate-docker-consistency.sh all && \
git diff --name-only # sollte leer sein
```
#### Env-less
```bash
DOCKER_SSOT_MODE=envless bash scripts/generate-compose-files.sh all development && \
DOCKER_SSOT_MODE=envless bash scripts/validate-docker-consistency.sh all && \
git diff --name-only # sollte leer sein
```
---
## 🔄 Automatisierte Workflows
| Workflow | Zweck | Trigger |
|------------------------------------------------------------------|--------------------------------------|-------------------|
| [ci-main.yml](.github/workflows/ci-main.yml) | Build, Test, OpenAPI-Lint, Docs-Lint | Push/PR |
| [ssot-guard.yml](.github/workflows/ssot-guard.yml) | Docker SSoT Validierung | Push/PR |
| [docs-kdoc-sync.yml](.github/workflows/docs-kdoc-sync.yml) | KDoc → YouTrack Sync | workflow_dispatch |
| [integration-tests.yml](.github/workflows/integration-tests.yml) | Integration Tests | Push/PR |
| [deploy-proxmox.yml](.github/workflows/deploy-proxmox.yml) | Deployment zu Proxmox | workflow_dispatch |
---
## 📜 Lizenz
[MIT License](LICENSE)
Für detailliertere Anleitungen, wie z.B. das Starten einzelner Services oder das Frontend-Setup, siehe die **[-> Lokale Setup-Anleitung](./docs/02_Onboarding/start-local.md)**.
---
## 🤝 Contributing
Bitte lies [docs/02_Onboarding/Development/branchschutz-und-pr-workflow.md](docs/02_Onboarding/Development/branchschutz-und-pr-workflow.md) für den
PR-Workflow.
Beiträge sind willkommen. Bitte beachte unseren [**-> Branch- und PR-Workflow**](./docs/02_Onboarding/branchschutz-und-pr-workflow.md).
---
## 📜 Lizenz
## 📞 Support & Kontakt
- **Bugs**: [GitHub Issues](https://github.com/StefanMoCoAt/meldestelle/issues)
- **Discussions**: [GitHub Discussions](https://github.com/StefanMoCoAt/meldestelle/discussions)
- **Dokumentation**: [YouTrack Wissensdatenbank](https://meldestelle-pro.youtrack.cloud/articles/MP-A-24)
---
**Version**: 2.0.0 (nach Dokumentations-Refactoring)
**letzte Aktualisierung**: 31. Oktober 2025
Dieses Projekt steht unter der [MIT License](LICENSE).