1. 01-systemueberblick.md - große fachliche und technische Sicht.
2. 02-entwicklerhandbuch.md - wie man im Code arbeitet.
3. 03-betriebshandbuch.md - wie man das System lokal und produktionsnah betreibt.
4. 04-lokaler-start-und-troubleshooting.md - Start, Checks und typische Fehler.
5. 05-architekturentscheidungen.md - wichtige Entscheidungen und Alternativen.
6. 06-security-handbuch.md - Keycloak, Rollen, JWT und API-Schutz.
7. 07-observability-handbuch.md - Metriken, Health, Prometheus, Grafana.
8. 08-resilience-handbuch.md - Retry, Timeout, Circuit Breaker, Rate Limiting.
9. 09-datenbankbetrieb-handbuch.md - Migration, Backup, Restore, Retention.
10. 10-cicd-deployment-handbuch.md - CI/CD, Quality Gates, Docker, Kubernetes, OpenShift.
11. 11-teststrategie-handbuch.md - Testpyramide und Testcontainers.
12. 12-fehlerkatalog-und-runbooks.md - konkrete Fehlerfälle und Reaktion.
13. 13-glossar.md - zentrale Begriffe.
14. 14-dateien-und-ordnerkarte.md - wo liegt was?
15. 15-lernplan.md - wie man das Projekt als Lernpfad nutzt.

Die Dokumentation folgt drei Ebenen:

• Lern-Ebene: Begriffe, Architektur und Entscheidungen verstehen.
• Praxis-Ebene: Container starten, REST Flow testen, Metriken ansehen.
• Betriebs-Ebene: Fehler erkennen, Runbooks nutzen, Security und Backup verstehen.

---

Das Projekt simuliert eine realistische Enterprise-Plattform rund um Order, Billing, Security, Messaging, Observability und Betrieb. Es ist bewusst nicht als Mini-Beispiel gedacht, sondern als kompaktes Labor, in dem typische Enterprise-Schnittstellen und Betriebsfragen sichtbar werden.

Der fachliche Kern ist ein Order Acceptance Flow:

1. Ein Client ruft einen REST-Endpunkt auf.
2. Die Runtime prüft über Spring Security, ob der JWT die richtige Rolle enthält.
3. Der Application Service erstellt oder akzeptiert eine Bestellung.
4. Der Payment Gateway Adapter ruft einen Mock Payment Provider auf.
5. Die Bestellung wird in PostgreSQL gespeichert.
6. Gleichzeitig wird ein Outbox Event geschrieben.
7. Ein Relay veröffentlicht das Event nach RabbitMQ.
8. Ein Billing Consumer reagiert auf das Event.
9. Observability-Komponenten messen Zustand, Fehler und Durchsatz.

Die Struktur folgt Ports and Adapters:

Domain
  keine Framework-Abhängigkeit

Application
  koordiniert Use Cases

Ports
  fachliche Verträge für Infrastruktur

Adapters
  PostgreSQL, RabbitMQ, WireMock, Payment, Outbox

Runtime
  Spring Boot, Security, Scheduling, REST, Actuator

Der wichtigste Lernpunkt: Fachlogik soll nicht von PostgreSQL, RabbitMQ, Keycloak oder Spring Security abhängig sein. Diese Dinge sitzen am Rand.

Synchronous Flow

Client -> REST -> Security -> Use Case -> Payment Provider -> PostgreSQL -> Response

Dieser Flow ist direkt sichtbar. Wenn Payment langsam oder fehlerhaft ist, muss Resilience greifen.

Asynchronous Flow

Use Case -> Outbox -> Relay -> RabbitMQ -> Billing Consumer

Dieser Flow zeigt lose Kopplung. Billing hängt nicht direkt im REST Request, sondern reagiert später auf Events.

Operational Flow

Runtime -> Actuator -> Prometheus -> Grafana -> Alert/Runbook

Dieser Flow zeigt, wie Betrieb und Entwicklung zusammenarbeiten.

---

Das Maven-Projekt ist modular aufgebaut. Änderungen sollen immer in der passenden Schicht landen.

maven-project/
├── domain
├── ports
├── application
├── adapters
├── runtime
└── integration-tests

Neue fachliche Regeln gehören zuerst in domain. Beispiel: Eine Bestellung darf nicht ohne Position angenommen werden. Diese Regel darf nicht in einem REST Controller oder Repository versteckt werden.

// Pattern: Aggregate Root - Order schützt fachliche Invarianten zentral.
public final class Order {
    private final OrderId id;
    private final List<OrderLine> lines;
    private OrderStatus status;

    private Order(OrderId id, List<OrderLine> lines) {
        if (lines == null || lines.isEmpty()) {
            throw new DomainRuleViolation("Eine Bestellung braucht mindestens eine Position.");
        }

        this.id = id;
        this.lines = List.copyOf(lines);
        this.status = OrderStatus.DRAFT;
    }
}

Die Runtime darf Application, Ports und Adapters kennen. Die Domain darf nichts von Runtime, Spring, PostgreSQL oder RabbitMQ kennen.

1. Fachliche Sprache notieren.
2. Domain-Regeln ergänzen.
3. Port definieren, falls Infrastruktur nötig ist.
4. Application Service schreiben.
5. Adapter implementieren.
6. Runtime verdrahten.
7. Tests ergänzen.
8. Doku und Runbook aktualisieren.

Wenn ein Fraud Provider ergänzt wird, sollte die Application nur einen Port sehen:

public interface FraudGateway {
    FraudDecision check(Order order);
}

Die konkrete HTTP-Kommunikation gehört in einen Adapter:

// Pattern: Gateway Adapter - externer Fraud Provider wird gekapselt.
public final class WireMockFraudGateway implements FraudGateway {
    private final RestClient restClient;

    public FraudDecision check(Order order) {
        return restClient.post()
                .uri("/fraud/check")
                .body(order.id().value())
                .retrieve()
                .body(FraudDecision.class);
    }
}

• Entwurfsmuster im Code kurz kommentieren.
• Keine Business-Regeln im Controller verstecken.
• Keine Datenbankdetails in Domain-Klassen.
• Keine langen Monster-Methoden ohne Zerlegung.
• Adapter dürfen technisch sein, Application Services sollen lesbar bleiben.
• Jede neue externe Integration braucht ein Runbook und ein Fehlerbild.

docker compose up -d
cd maven-project
mvn -q -DskipTests package
mvn -pl runtime spring-boot:run

---

Das System soll lokal nachvollziehbar, in Kubernetes/OpenShift übertragbar und operativ beobachtbar sein. Betrieb bedeutet hier nicht nur "Container läuft", sondern: Start, Health, Logs, Metriken, Backup, Restore, Security und Incident Response sind dokumentiert.

docker compose ps
curl -fsS http://localhost:8082/realms/order-platform/.well-known/openid-configuration
curl -fsS http://localhost:8089/__admin/mappings
curl -fsS http://localhost:9090/-/ready

Jeder Request soll eine Correlation ID erhalten. Dadurch kann man REST-Aufruf, Payment-Aufruf, Outbox-Eintrag und Consumer-Log zusammenführen.

X-Correlation-Id: 7f4d1c...

Für Datenbankmigrationen, große Konfigurationsänderungen und Keycloak-Realm-Änderungen sollte ein Wartungsfenster geplant werden. Kleine Runtime-Releases können bei Kubernetes/OpenShift über Rolling Updates erfolgen.

---

cp .env.example .env
docker compose up -d
cd maven-project
mvn -q -DskipTests package
mvn -pl runtime spring-boot:run

./scripts/security/call-secured-order-flow.sh

curl -X POST http://localhost:8080/api/orders/ORD-LOCAL-1/accept \
  -H "Authorization: Bearer ${TOKEN}"

Danach prüfen:

select event_id, aggregate_id, event_type, status
from outbox.events
order by event_id desc;

Symptom:

bind: address already in use

Prüfen:

docker ps
lsof -i :5432
lsof -i :8082

Lösung:

docker compose down

Oder Ports in docker-compose.yml ändern.

Mögliche Ursachen:

• Realm wurde noch nicht importiert.
• Keycloak ist noch nicht vollständig gestartet.
• Falscher Client order-runtime.
• User oder Passwort falsch.
• Runtime erwartet einen anderen Issuer.

Prüfung:

curl http://localhost:8082/realms/order-platform/.well-known/openid-configuration

Ursachen:

• Runtime Scheduler läuft nicht.
• RabbitMQ ist nicht erreichbar.
• Routing Key ist falsch.
• Publisher wirft Exception.

Prüfung:

select * from outbox.events order by event_id desc;

RabbitMQ prüfen:

http://localhost:15672

Prüfen:

curl http://localhost:8080/actuator/prometheus
curl http://localhost:9090/targets

Wenn Prometheus die Runtime nicht erreicht, ist host.docker.internal auf der Plattform eventuell anders zu konfigurieren.

---

Entscheidung: Das Projekt nutzt domain, ports, application, adapters, runtime und integration-tests.

Grund: Die Modulgrenzen machen Abhängigkeiten sichtbar. Ein einzelnes Projekt wäre schneller, aber fachliche und technische Klassen würden leichter vermischt.

Konsequenz: Mehr Struktur, mehr POM-Dateien, aber bessere Lernwirkung.

Entscheidung: Externe Systeme werden über Ports abstrahiert.

Alternativen: Direkt JdbcTemplate, RabbitTemplate oder RestClient im Use Case verwenden.

Bewertung: Direkte technische Abhängigkeiten sind am Anfang schneller, führen aber zu schlechter testbarer Fachlogik.

Entscheidung: Events werden zuerst in PostgreSQL gespeichert und danach durch ein Relay publiziert.

Grund: Vermeidung des Dual-Write-Problems zwischen Datenbank und Message Broker.

Konsequenz: Zusätzliche Tabelle, Relay-Logik und Monitoring nötig.

Entscheidung: OIDC/JWT wird nicht nur simuliert, sondern über Keycloak bereitgestellt.

Grund: Rollen, Claims, Issuer und Tokenfehler sind in Enterprise-Projekten zentrale Fehlerquellen.

Konsequenz: Mehr Container-Setup, aber deutlich realistischer.

Entscheidung: Payment und Fraud werden als Mock Provider umgesetzt.

Grund: Externe Anbieter sind teuer, instabil oder nicht lokal verfügbar. WireMock erlaubt klare Verträge.

Entscheidung: Alle Systeme laufen lokal per Compose.

Grund: Ein Lernprojekt braucht reproduzierbaren Start ohne Cloud-Abhängigkeit.

Entscheidung: Compose bleibt Lern- und Entwicklungsmodus. Kubernetes/OpenShift sind Deployment-Profile.

Grund: Beide Welten haben andere Ziele. Compose ist schnell, Kubernetes ist produktionsnäher.

Entscheidung: Prometheus-Regeln und Grafana Dashboards liegen als Dateien im Projekt.

Grund: Monitoring darf kein manuelles Klickprodukt sein.

Entscheidung: Retry, Timeout und Circuit Breaker sitzen um externe Calls, nicht in der Domain.

Grund: Resilience ist technische Schutzlogik. Die Fachlogik soll nicht wissen, ob ein Provider gerade instabil ist.

---

Die Anwendung nutzt Keycloak als Identity Provider. Die Runtime ist ein OAuth2 Resource Server. REST-Endpunkte werden über Rollen geschützt.

Client -> Keycloak Token Endpoint -> JWT -> Runtime -> Spring Security -> Controller

Security bleibt in der Runtime-Schicht. Domain und Application sollen keine JWT Claims auswerten.

TOKEN="$(
  curl -s -X POST "http://localhost:8082/realms/order-platform/protocol/openid-connect/token" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "client_id=order-runtime" \
    -d "grant_type=password" \
    -d "username=order-admin" \
    -d "password=admin" | python -c "import sys,json; print(json.load(sys.stdin)['access_token'])"
)"

curl -i -X POST "http://localhost:8080/api/orders/ORD-SEC-1/accept" \
  -H "Authorization: Bearer ${TOKEN}"

Erwartung: 200 OK.

Mit order-reader darf der POST nicht erlaubt sein. Erwartung: 403 Forbidden.

• Keine Default-Passwörter in Produktion.
• Realm-Konfiguration versionieren.
• Client Secrets und Admin-Passwörter als Secrets verwalten.
• Token-Lebensdauer bewusst wählen.
• Rollen nicht direkt aus UI-Wünschen ableiten, sondern fachlich modellieren.

---

Observability beantwortet drei Fragen:

1. Ist das System erreichbar?
2. Funktionieren fachliche Flows?
3. Wo entsteht ein Fehler oder Engpass?

Actuator Health zeigt technische Bereitschaft. Ein Health Check darf nicht nur sagen, dass der Prozess läuft. Wichtig sind Abhängigkeiten:

• PostgreSQL erreichbar?
• Outbox Backlog im Rahmen?
• RabbitMQ erreichbar?
• Payment Provider erreichbar oder Circuit offen?

Jeder Request soll mit einer Correlation ID nachvollziehbar sein:

Client Request
  -> Runtime Log
  -> Payment Call
  -> Outbox Event
  -> Consumer Log

Prometheus scrapt:

/actuator/prometheus

Wichtige PromQL-Ideen:

rate(http_server_requests_seconds_count[5m])

sum(order_outbox_backlog)

Dashboards sollten nicht nur technische Kurven zeigen, sondern Fragen beantworten:

• Kommen Bestellungen rein?
• Werden Events publiziert?
• Gibt es Backlog?
• Steigt die Fehlerrate?
• Ist der Payment Provider langsam?

Gute Alerts sind handlungsorientiert. Ein Alert soll ein Runbook verlinken und nicht nur "rot" sein.

• Keine Tokens loggen.
• Keine Passwörter loggen.
• Fachliche IDs erlaubt, personenbezogene Daten vermeiden.
• Correlation ID immer mitschreiben.
• Fehler mit Ursache und Kontext, aber ohne Secrets.

---

Resilience schützt das System vor instabilen Abhängigkeiten. Im Projekt ist besonders der Payment Provider relevant.

Eine sinnvolle Kette:

Rate Limit -> Bulkhead -> Timeout -> Retry -> Circuit Breaker -> Fallback/Error Response

Timeout verhindert, dass Threads oder Verbindungen hängen bleiben. Ein Timeout muss kleiner sein als der Client-Timeout vor der Runtime.

Retry nur bei Fehlern verwenden, die wirklich transient sind. Nicht jeder Fehler darf wiederholt werden.

Nicht sinnvoll:

400 Bad Request -> Retry

Sinnvoll:

503 Service Unavailable -> Retry mit Backoff

Der Circuit Breaker öffnet, wenn zu viele Fehler auftreten. Danach werden Calls kurzfristig abgelehnt, damit sich der Provider erholen kann.

APIs sollen stabile Fehlerformate liefern:

{
  "code": "PAYMENT_TEMPORARILY_UNAVAILABLE",
  "message": "Payment Provider ist aktuell nicht erreichbar.",
  "correlationId": "..."
}

1. Grafana Payment Dashboard prüfen.
2. Circuit Breaker Status prüfen.
3. WireMock/Provider Health prüfen.
4. Logs mit Correlation ID suchen.
5. Outbox Backlog prüfen.
6. Falls Provider down: Incident klassifizieren.
7. Nach Wiederherstellung Retry/Backlog beobachten.

---

PostgreSQL ist im Projekt nicht nur Datenspeicher, sondern auch Teil des Integrationsmusters durch die Outbox. Deshalb braucht die Datenbank eigene Betriebsdoku.

Migrationen laufen über Flyway. Jede Änderung am Schema soll als neue Migration versioniert werden.

V1__create_order_and_outbox.sql
V2__outbox_relay_indexes.sql

Backup-Script:

./scripts/database/backup-postgres.sh

Grundregel:

• Backup regelmäßig testen.
• Restore regelmäßig üben.
• Backup ohne Restore-Test ist nur eine Hoffnung.

Restore-Script:

./scripts/database/restore-postgres.sh backup-file.sql

Outbox Events dürfen nicht unbegrenzt wachsen. Publizierte Events können nach einer definierten Zeit archiviert oder gelöscht werden.

Beispiel:

delete from outbox.events
where status = 'PUBLISHED'
  and published_at < now() - interval '30 days';

select status, count(*)
from outbox.events
group by status;

select count(*)
from order_platform.orders;

select installed_rank, version, description, success
from flyway_schema_history
order by installed_rank desc;

• Keine manuellen Schemaänderungen ohne Migration.
• Indizes für Outbox Status und Event ID prüfen.
• Connection Pool überwachen.
• Lange Transaktionen vermeiden.
• Backup-Verschlüsselung und Aufbewahrung definieren.
• Restore-Zeit messen und dokumentieren.

---

Die Pipeline soll nicht nur bauen, sondern Qualität sichtbar erzwingen.

./scripts/quality/run-quality-gates.sh

./scripts/deploy/build-runtime-image.sh

kubectl apply -k deploy/kubernetes/overlays/local

oc apply -k deploy/kubernetes/overlays/openshift

helm upgrade --install order-runtime deploy/helm/order-runtime

Ein Release ist erst dann fertig, wenn:

• Tests grün sind.
• SBOM erzeugt wurde.
• Lizenzbericht geprüft wurde.
• Docker Image gebaut wurde.
• Deployment Manifest gerendert wurde.
• Runbooks aktualisiert wurden.
• Version und Release Notes stimmen.

checkout
  -> setup java
  -> mvn verify
  -> testcontainers/e2e optional
  -> sbom
  -> license report
  -> docker build
  -> manifest render
  -> release artifact

---

Tests sollen nicht nur Code Coverage erzeugen. Sie sollen Risiken absichern.

Viele Domain Tests
  -> Application Tests
  -> Adapter Tests
  -> Contract Tests
  -> Security Tests
  -> wenige E2E Tests

Testcontainers ist für Infrastrukturtests gedacht. Nicht jeder Test sollte Container starten.

Gute Kandidaten:

• PostgreSQL Schema/Migration.
• RabbitMQ Verbindung und Routing.
• WireMock Providervertrag.
• E2E Happy Path.

Schlechte Kandidaten:

• einfache Value Object Regeln.
• reine Berechnung.
• Mapping ohne Infrastruktur.

Ein guter E2E-Test prüft einen kritischen Pfad:

REST -> Security -> Use Case -> Payment -> DB -> Outbox -> RabbitMQ -> Consumer

Aber er soll nicht alle fachlichen Varianten abdecken. Sonst wird er langsam und fragil.

Testdaten müssen reproduzierbar sein. Keine versteckten lokalen Datenbanken. Keine Abhängigkeit von vorheriger Testreihenfolge.

Wenn ein E2E-Test fehlschlägt:

1. Container Logs prüfen.
2. Ports und Health prüfen.
3. Testdaten prüfen.
4. WireMock Requests prüfen.
5. DB Zustand prüfen.
6. RabbitMQ Queue prüfen.

---

Symptom: API antwortet mit 401 Unauthorized.

Wahrscheinliche Ursachen:

• Kein Token gesendet.
• Token abgelaufen.
• Issuer stimmt nicht.
• Keycloak nicht erreichbar.

Runbook:

curl http://localhost:8082/realms/order-platform/.well-known/openid-configuration
./scripts/security/get-keycloak-token.sh order-admin admin

Symptom: Token gültig, Zugriff verboten.

Ursache: Rolle fehlt.

Runbook:

• JWT Claims prüfen.
• realm_access.roles prüfen.
• Mapping zu ROLE_* prüfen.
• Security-Regel für Endpunkt prüfen.

Symptom: Viele Events bleiben NEW.

Ursachen:

• Relay läuft nicht.
• RabbitMQ down.
• Routing falsch.
• Publisher wirft Exception.

Runbook:

select status, count(*) from outbox.events group by status;

RabbitMQ Management prüfen:

http://localhost:15672

Symptom: Bestellannahme langsam oder fehlerhaft.

Runbook:

• WireMock Mapping prüfen.
• Resilience Dashboard prüfen.
• Circuit Breaker Status prüfen.
• Correlation ID in Logs verfolgen.

Symptom: Runtime startet nicht, Flyway Fehler.

Runbook:

select * from flyway_schema_history order by installed_rank desc;

• Fehlgeschlagene Migration nicht manuell überschreiben.
• Ursache analysieren.
• Korrektur als neue Migration erstellen.

Symptom: Grafana zeigt keine Daten.

Runbook:

curl http://localhost:8080/actuator/prometheus
curl http://localhost:9090/targets

Symptom: Container bleiben unhealthy oder starten nicht.

Runbook:

docker compose ps
docker compose logs postgres
docker compose logs keycloak
docker compose logs rabbitmq

---

Zentrale fachliche Einheit, die Invarianten schützt. Im Projekt ist Order ein Aggregate Root.

Koordiniert einen Use Case. Er enthält Ablaufsteuerung, aber keine technischen Details.

Technische Implementierung eines Ports. Beispiele: PostgreSQL Repository, RabbitMQ Publisher, WireMock Gateway.

Fachlicher Vertrag, den die Application benötigt. Der Port kennt keine konkrete Infrastruktur.

Muster, bei dem Events zuerst in derselben Datenbanktransaktion gespeichert und später veröffentlicht werden.

Job oder Prozess, der Outbox Events liest und an einen Message Broker publiziert.

Verteiler für Nachrichten. Im Projekt: order.events.

Schlüssel, mit dem RabbitMQ entscheidet, welche Queue eine Nachricht erhält.

Dead Letter Queue. Dort landen Nachrichten, die nicht verarbeitet werden konnten.

Anwendung, die Bearer Tokens validiert und Zugriffe schützt.

JSON Web Token. Enthält Claims wie Subject, Rollen und Ablaufzeit.

Isolierter Sicherheitsbereich mit Clients, Rollen und Usern.

Zeitreihen-Datenbank und Scraper für Metriken.

Dashboard-System zur Visualisierung von Metriken.

Resilience-Muster, das bei vielen Fehlern weitere Aufrufe temporär verhindert.

Resilience-Muster zur Isolation von Ressourcen.

Software Bill of Materials. Liste verwendeter Software-Komponenten.

Architecture Decision Record. Dokumentiert wichtige Architekturentscheidungen.

---

---

Dieser Lernplan hilft, das Projekt nicht nur zu öffnen, sondern systematisch zu verstehen.

• Root index.html öffnen.
• README.md lesen.
• Maven Module ansehen.
• domain, ports, application, adapters, runtime vergleichen.

Übung:

cd maven-project
mvn -q -DskipTests package

• Docker Compose starten.
• Adminer, RabbitMQ, Keycloak, Grafana öffnen.
• WireMock Mapping ansehen.

Übung:

docker compose up -d
docker compose ps

• Token holen.
• geschützten Flow testen.
• order-admin und order-reader vergleichen.

Übung:

./scripts/security/call-secured-order-flow.sh

• Outbox Tabelle ansehen.
• Relay Job verstehen.
• RabbitMQ Queue prüfen.

Übung:

select status, count(*) from outbox.events group by status;

• Actuator Prometheus Endpoint öffnen.
• Grafana Dashboard ansehen.
• Timeout/Fehlerfall über WireMock simulieren.

• Testcontainers Struktur verstehen.
• E2E Tests ausführen.
• GitHub Actions Pipeline lesen.

Übung:

./scripts/tests/run-phase4-e2e.sh
./scripts/quality/run-quality-gates.sh

• Dockerfile verstehen.
• Kubernetes/Kustomize lesen.
• Helm Chart lesen.
• Backup/Restore Runbook durcharbeiten.

Ergänze einen Fraud Provider:

1. FraudGateway Port definieren.
2. WireMock Fraud Mapping erstellen.
3. Application Service erweitern.
4. Resilience für Fraud Call ergänzen.
5. Metrik fraud_checks_total ergänzen.
6. Testcontainers/Contract Test ergänzen.
7. Doku und Runbook aktualisieren.