Meldestelle

Überblick

Meldestelle ist ein modulares System zur Verwaltung von Pferdesportveranstaltungen. Das System ermöglicht die Registrierung von Pferden, Mitgliedern und Veranstaltungen sowie die Verwaltung von Stammdaten.

Das Projekt wurde kürzlich auf eine modulare Architektur migriert, um die Wartbarkeit und Erweiterbarkeit zu verbessern.

Systemanforderungen

• Java 21
• Kotlin 2.2.10
• Gradle 8.11+ (automatischer Download über Gradle Wrapper)
• Docker und Docker Compose (v2.0+)

Infrastruktur

Das System nutzt folgende Dienste:

• PostgreSQL 16: Primäre Datenbank
• Redis 7: Caching
• Keycloak 23.0: Authentifizierung und Autorisierung
• Kafka 7.5.0: Messaging und Event-Streaming
• Zipkin: Distributed Tracing
• Prometheus & Grafana: Monitoring (optional)

Projektstruktur

Das Projekt ist in folgende Hauptmodule unterteilt:

• core: Gemeinsame Kernkomponenten

  • core-domain: Domänenmodelle und Geschäftslogik
  • core-utils: Allgemeine Hilfsfunktionen

• masterdata: Umfassende Verwaltung von Stammdaten für Pferdesportveranstaltungen

  • Funktionalität: Länder (ISO-Codes, EU/EWR-Mitgliedschaft), Bundesländer (OEPS/ISO-Codes), Altersklassen (Teilnahmeberechtigung), Turnierplätze (Typ, Abmessungen, Boden)
  • API-Endpunkte: 37 REST-Endpunkte mit vollständiger CRUD-Funktionalität
  • Geschäftslogik: Validierung, Duplikatsprüfung, Berechtigung, Eignung für Disziplinen
  • masterdata-api: REST-Controller und DTO-Definitionen
  • masterdata-application: Use Cases und Geschäftslogik
  • masterdata-domain: Domänenmodelle und Repository-Interfaces
  • masterdata-infrastructure: Datenbankzugriff und Persistierung
  • masterdata-service: Spring Boot Service-Implementierung

• members: Mitgliederverwaltung

  • members-api: API-Definitionen
  • members-application: Anwendungslogik
  • members-domain: Domänenmodelle
  • members-infrastructure: Infrastrukturkomponenten
  • members-service: Service-Implementierung

• horses: Pferderegistrierung

  • horses-api: API-Definitionen
  • horses-application: Anwendungslogik
  • horses-domain: Domänenmodelle
  • horses-infrastructure: Infrastrukturkomponenten
  • horses-service: Service-Implementierung

• events: Veranstaltungsverwaltung

  • events-api: API-Definitionen
  • events-application: Anwendungslogik
  • events-domain: Domänenmodelle
  • events-infrastructure: Infrastrukturkomponenten
  • events-service: Service-Implementierung

• infrastructure: Gemeinsame Infrastrukturkomponenten

  • auth: Authentifizierung
  • cache: Caching
  • event-store: Event-Speicher
  • gateway: API-Gateway
  • messaging: Messaging-Infrastruktur
  • monitoring: Monitoring-Komponenten

• client: Client-Anwendungen

  • common-ui: Gemeinsame UI-Komponenten
  • desktop-app: Desktop-Anwendung
  • web-app: Web-Anwendung

Installation und Setup

Voraussetzungen

Stellen Sie sicher, dass Java 21, Docker und Docker Compose installiert sind.

Docker-Infrastruktur

Das System bietet verschiedene Docker-Konfigurationen für unterschiedliche Umgebungen:

Entwicklungsumgebung (Schnellstart)

# Infrastruktur starten
docker compose up -d

# Status überprüfen
docker compose ps

# Logs anzeigen
docker compose logs -f

Dies startet alle erforderlichen Dienste wie PostgreSQL, Redis, Keycloak, Kafka, Zipkin und optional Prometheus und Grafana.

Produktionsumgebung

Für die Produktionsumgebung siehe README-PRODUCTION.md - enthält:

• Umfassende Sicherheitskonfiguration
• SSL/TLS-Setup
• Detaillierte Troubleshooting-Anleitung
• Backup- und Wiederherstellungsverfahren

Umgebungsvariablen

Für die Konfiguration von Umgebungsvariablen siehe README-ENV.md - enthält:

• Vollständige Umgebungsvariablen-Dokumentation
• Validierungsskripte
• Konfigurationsbeispiele

Validierung und Troubleshooting

# Umgebungsvariablen validieren
./validate-env.sh

# Docker-Compose Konfiguration validieren
./validate-docker-compose.sh

# Service-Status überprüfen
docker-compose ps

# Service-Logs anzeigen
docker-compose logs [service-name]

Projekt bauen

./gradlew build

Dienste starten

# Gateway starten
./gradlew :infrastructure:gateway:bootRun

# Masterdata-Service starten
./gradlew :masterdata:masterdata-service:bootRun

# Members-Service starten
./gradlew :members:members-service:bootRun

# Horses-Service starten
./gradlew :horses:horses-service:bootRun

# Events-Service starten
./gradlew :events:events-service:bootRun

Client-Anwendungen starten

# Desktop-Anwendung starten
./gradlew :client:desktop-app:run

# Web-Anwendung bauen
./gradlew :client:web-app:build

Entwicklung

Aktuelle Migrationshinweise

Das Projekt wurde kürzlich von einer monolithischen Struktur zu einer modularen Architektur migriert. Die Migration umfasste:

• Umzug von :shared-kernel zu core-Modulen
• Umzug von :master-data zu masterdata-Modulen
• Umzug von :member-management zu members-Modulen
• Umzug von :horse-registry zu horses-Modulen
• Umzug von :event-management zu events-Modulen
• Umzug von :api-gateway zu infrastructure/gateway
• Umzug von :composeApp zu client-Modulen

Es gibt noch einige offene Probleme, insbesondere bei den Client-Modulen, die Kotlin Multiplatform und Compose Multiplatform verwenden.

Entwicklungsrichtlinien

• Verwenden Sie die in der Projektstruktur definierten Module
• Folgen Sie den Architekturentscheidungen (ADRs) im Verzeichnis docs/architecture/adr (verfügbar in Deutsch mit Dateiendung -de.md)
• Verwenden Sie die C4-Diagramme im Verzeichnis docs/architecture/c4 für einen Überblick über die Systemarchitektur (verfügbar in Deutsch mit Dateiendung -de.puml)
• Verwenden Sie die Datenmodelle aus docs/architecture/data-model

Tests ausführen

./gradlew test

Docker Troubleshooting (Entwicklungsumgebung)

Häufige Probleme und Lösungen

1. Services starten nicht

# Alle Services stoppen und neu starten
docker compose down
docker compose up -d

# Einzelnen Service neu starten
docker compose restart [service-name]

# Service-Logs überprüfen
docker compose logs [service-name]

2. Port bereits belegt

# Verwendete Ports prüfen
netstat -tulpn | grep :[port]
# oder
lsof -i :[port]

# Ports in .env anpassen
nano .env
# Beispiel: API_PORT=8081 statt 8080

3. Datenbank-Verbindungsfehler

# PostgreSQL-Status prüfen
docker compose exec postgres pg_isready -U meldestelle

# Datenbank-Logs anzeigen
docker compose logs postgres

# Verbindung manuell testen
docker compose exec postgres psql -U meldestelle -d meldestelle

4. Keycloak-Authentifizierung fehlgeschlagen

# Keycloak-Status prüfen
docker compose logs keycloak

# Keycloak Admin-Console öffnen
# http://localhost:8180/admin (admin/admin)

# Keycloak-Datenbank zurücksetzen
docker compose down
docker volume rm meldestelle_postgres-data
docker compose up -d

5. Kafka-Verbindungsprobleme

# Kafka-Status prüfen
docker compose exec kafka kafka-topics --bootstrap-server localhost:9092 --list

# Zookeeper-Status prüfen
docker compose exec zookeeper nc -z localhost 2181

# Kafka-Logs anzeigen
docker compose logs kafka zookeeper

6. Speicherplatz-Probleme

# Docker-Speicherverbrauch prüfen
docker system df

# Ungenutzte Ressourcen bereinigen
docker system prune -f

# Volumes bereinigen (ACHTUNG: Datenverlust!)
docker system prune -f --volumes

7. Performance-Probleme

# Ressourcenverbrauch überwachen
docker stats

# Container-Limits anpassen (in docker-compose.yml)
# deploy:
#   resources:
#     limits:
#       memory: 1G
#       cpus: '0.5'

Nützliche Docker-Befehle

# Alle Services mit Logs starten
docker compose up

# Services im Hintergrund starten
docker compose up -d

# Bestimmte Services starten
docker compose up postgres redis

# Services stoppen
docker compose stop

# Services stoppen und Container entfernen
docker compose down

# Services mit Volume-Bereinigung stoppen
docker compose down -v

# Container-Shell öffnen
docker compose exec [service-name] /bin/bash
# oder für Alpine-basierte Images:
docker compose exec [service-name] /bin/sh

# Konfiguration validieren
docker compose config

# Service-Status anzeigen
docker compose ps

# Logs aller Services anzeigen
docker compose logs

# Logs eines bestimmten Services verfolgen
docker compose logs -f [service-name]

Dokumentation

Weitere Dokumentation finden Sie im docs-Verzeichnis:

• API-Dokumentation: docs/api
• Architektur: docs/architecture
• Entwicklungsrichtlinien: docs/development
• Diagramme: docs/diagrams
• Betriebsanleitung: docs/operations
• Postman-Sammlungen: docs/postman

Lizenz

Siehe LICENSE Datei.

Stand

Letzte Aktualisierung: 14. September 2025