454 lines
15 KiB
Markdown
454 lines
15 KiB
Markdown
# Meldestelle
|
||
|
||
> Modulares System für Pferdesportveranstaltungen mit Domain-Driven Design
|
||
|
||
[](https://github.com/StefanMoCoAt/meldestelle/actions)
|
||
[](https://github.com/StefanMoCoAt/meldestelle/actions)
|
||
[](https://opensource.org/licenses/MIT)
|
||
|
||
---
|
||
|
||
## 🚀 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/how-to/start-local.md](docs/how-to/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/adr)
|
||
- [📐 C4-Diagramme](docs/c4)
|
||
- [🛠️ Developer Guides](docs/how-to)
|
||
- [📑 Projekt-Guidelines (Master)](.junie/guidelines/master-guideline.md)
|
||
|
||
Zusätzliche zentrale Guidelines:
|
||
|
||
- [Coding Standards](.junie/guidelines/project-standards/coding-standards.md)
|
||
- [Testing Standards](.junie/guidelines/project-standards/testing-standards.md)
|
||
- [Documentation Standards](.junie/guidelines/project-standards/documentation-standards.md)
|
||
- [Architecture Principles](.junie/guidelines/project-standards/architecture-principles.md)
|
||
- [Web App Guideline](.junie/guidelines/technology-guides/web-app-guideline.md)
|
||
- Docker Guides:
|
||
- [Docker Overview](.junie/guidelines/technology-guides/docker/docker-overview.md)
|
||
- [Docker Architecture](.junie/guidelines/technology-guides/docker/docker-architecture.md)
|
||
- [Docker Development](.junie/guidelines/technology-guides/docker/docker-development.md)
|
||
- [Docker Production](.junie/guidelines/technology-guides/docker/docker-production.md)
|
||
- [Docker Monitoring](.junie/guidelines/technology-guides/docker/docker-monitoring.md)
|
||
- [Docker Troubleshooting](.junie/guidelines/technology-guides/docker/docker-troubleshooting.md)
|
||
- Process Guide: [Trace Bullet](.junie/guidelines/process-guides/trace-bullet-guideline.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/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)
|
||
|
||
```bash
|
||
# Versionen anzeigen
|
||
bash scripts/docker-build.sh --versions
|
||
|
||
# Compose-Files generieren (Kompatibilitätsmodus)
|
||
bash scripts/generate-compose-files.sh all development
|
||
|
||
# Konsistenz validieren (Kompatibilitätsmodus)
|
||
bash scripts/validate-docker-consistency.sh all
|
||
```
|
||
|
||
### 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:** [Docker Development Guide](.junie/guidelines/technology-guides/docker/docker-development.md#-vollständige-makefile-referenz)
|
||
|
||
### 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)
|
||
|
||
---
|
||
|
||
## 🤝 Contributing
|
||
|
||
Bitte lies [docs/how-to/branchschutz-und-pr-workflow.md](docs/how-to/branchschutz-und-pr-workflow.md) für den
|
||
PR-Workflow.
|
||
|
||
---
|
||
|
||
## 📞 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
|