meldestelle/README.md

Meldestelle

Modulares System für Pferdesportveranstaltungen mit Domain-Driven Design

---

🚀 Quick Start

# 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 :members:members-service:bootRun
# oder – falls zentral gewollt und unterstützt
# ./gradlew bootRun

Vollständige Anleitung: docs/how-to/start-local.md

---

📚 Dokumentation

Single Source of Truth: YouTrack

Die Hauptdokumentation befindet sich in der YouTrack Wissensdatenbank:

👉 Meldestelle Command Center

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 - Übersicht aller Repository-Dokumentation
• 🏛️ Architecture Decision Records
• 📐 C4-Diagramme
• 🛠️ Developer Guides
• 📑 Projekt-Guidelines (Master)

Zusätzliche zentrale Guidelines:

• Coding Standards
• Testing Standards
• Documentation Standards
• Architecture Principles
• Web App Guideline
• Docker Guides:
  • Docker Overview
  • Docker Architecture
  • Docker Development
  • Docker Production
  • Docker Monitoring
  • Docker Troubleshooting
• Process Guide: Trace Bullet

---

🏗️ 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

---

⚙️ 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/.env (z. B. ping-service.env)
  • config/env/infrastructure/.env (z. B. api-gateway.env)
  • config/env/clients/.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	21
Build	Gradle	9.1.0
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

Meldestelle/
├── 🗂️ client/                 # Client-Anwendungen
│   ├── desktop-app/
│   └── web-app/
├── 🗂️ core/                   # Gemeinsame Kern-Komponenten
│   ├── core-domain/
│   └── core-utils/
├── 🗂️ docs/                   # Minimale Entwickler-Dokumentation
│   ├── architecture/
│   └── how-to/
├── 🗂️ events/                 # Bounded Context: Veranstaltungsverwaltung
│   └── (analog zu members)
├── 🗂️ horses/                 # Bounded Context: Pferderegistrierung
│   └── (analog zu members)
├── 🗂️ infrastructure/         # Technische Infrastruktur
│   ├── auth/                  # Authentifizierung
│   ├── cache/                 # Caching (Redis)
│   ├── gateway/               # API Gateway (Spring Cloud Gateway)
│   ├── messaging/             # Kafka-Integration
│   └── monitoring/            # Observability
├── 🗂️ masterdata/             # Bounded Context: Stammdaten
│   └── (analog zu members)
└── 🗂️ members/                # Bounded Context: Mitgliederverwaltung
    ├── members-api/
    ├── members-application/
    ├── members-domain/
    ├── members-infrastructure/
    └── members-service/

---

🔒 Docker Single Source of Truth (SSoT)

Alle Versionen zentral in docker/versions.toml:

SSoT – Schnellstart (präzisiert)

# 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)

# 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):

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)

# 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)

# 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 :members:members-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

 ./gradlew test

Integration Tests

 ./gradlew integrationTest

Spezifisches Modul testen

 ./gradlew :members:members-service:test

---

🚢 Deployment

Lokale Entwicklung

Nur Infrastruktur (Postgres, Redis, Kafka, Keycloak)

 docker compose -f docker-compose.yaml up -d

Services über Gradle

 ./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 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

  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:

make help  # Zeigt alle verfügbaren Befehle

Wichtigste Befehle:

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:

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

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 scripts/docker-versions-update.sh update gradle 9.1.0 
 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 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

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	Build, Test, OpenAPI-Lint, Docs-Lint	Push/PR
ssot-guard.yml	Docker SSoT Validierung	Push/PR
docs-kdoc-sync.yml	KDoc → YouTrack Sync	workflow_dispatch
integration-tests.yml	Integration Tests	Push/PR
deploy-proxmox.yml	Deployment zu Proxmox	workflow_dispatch

---

📜 Lizenz

MIT License

---

🤝 Contributing

Bitte lies docs/how-to/branchschutz-und-pr-workflow.md für den PR-Workflow.

---

📞 Support & Kontakt

• Bugs: GitHub Issues
• Discussions: GitHub Discussions
• Dokumentation: YouTrack Wissensdatenbank

---

Version: 2.0.0 (nach Dokumentations-Refactoring)
letzte Aktualisierung: 31. Oktober 2025