---
type: ADR
status: ACTIVE
owner: Lead Architect
---
# ADR 001: Backend-Infrastruktur & Architekturentscheidungen

**Status:** AKZEPTIERT
**Datum:** 2026-01-15
**Autor:** Lead Architect
**Kontext:** „Operation Tracer Bullet" (Phase 1) – Härtung des `ping-service`.

---

## 1. Persistenzstrategie: JPA vs. Exposed

**Entscheidung:** **Hybrider Ansatz (Command/Query-Trennung)**
*   **Primär (Command/Write):** Wir verwenden **JPA (Hibernate)** für das Standard-„Write Model" in unseren Microservices.
    *   *Begründung:* Beste Integration mit Spring Data, Transaktionsverwaltung und Validierung. Standard für Enterprise Spring Boot.
*   **Sekundär (Query/Read/Batch):** Wir erlauben **Exposed** für komplexe Leseabfragen oder Bulk-Operationen, bei denen der JPA-Overhead zu hoch ist.
    *   *Begründung:* Kotlin-nativ, typsichere SQL-Generierung, bessere Performance bei leselastigen Operationen.

**Maßnahmen:**
*   Das Modul `backend/infrastructure/persistence` unterstützt **beide** Ansätze.
*   `ping-service` verwendet primär **JPA** für seine Entitäten (`PingEntity`).
*   JPA wird NICHT aus dem `ping-service` entfernt.
*   Exposed wird NICHT aus `infrastructure/persistence` entfernt.

## 2. Gemeinsames Security-Modul

**Entscheidung:** **Extraktion von `backend/infrastructure/security`**
*   **Begründung:** Wir folgen konsequent dem DRY-Prinzip (Don't Repeat Yourself). Die Sicherheitskonfiguration (OAuth2 Resource Server, JWT Converter, CORS, Global Method Security) ist für alle Microservices identisch.
*   **Umfang:**
    *   `SecurityConfig`: Standard `SecurityFilterChain`.
    *   `KeycloakRoleConverter`: Rollen aus JWT extrahieren.
    *   `CorsConfig`: Zentrale CORS-Richtlinie.

**Maßnahmen:**
*   `backend/infrastructure/security` erstellen.
*   Sicherheitslogik aus `ping-service` (falls vorhanden) in dieses Modul verschieben.

## 3. Messaging vs. Sync-Protokoll

**Entscheidung:** **REST-basiertes Pull (Phase 1) → Kafka (Phase 3)**
*   **Phase 1 (Tracer Bullet):** Für den einfachen `ping-service` wird Kafka noch NICHT verwendet.
    *   *Begründung:* Die „Tracer Bullet" soll einfach bleiben. Zuerst die HTTP/Auth-Kette validieren.
*   **Phase 3 (Offline-Sync):** Kafka wird später für das „Outbox Pattern" eingeführt.
    *   *Begründung:* Zuverlässige Event-Zustellung für Offline-Clients erfordert ein dauerhaftes Log.

**Maßnahmen:**
*   `reactor-kafka`-Abhängigkeit vorerst aus `ping-service` entfernen, um die Komplexität zu reduzieren.
*   Fokus auf `PingEntity` (JPA) und REST-Endpunkte.

## 4. Datenbank-Migration (Flyway)

**Entscheidung:** **Datenbank pro Service (Option A)**
*   **Begründung:** Autonomie der Microservices. Jeder Service besitzt sein eigenes Schema.
*   **Ablageort:** `src/main/resources/db/migration` innerhalb jedes Service-Moduls.
*   **Benennung:** `V{Version}__{Beschreibung}.sql` (z.B. `V1__init_ping_schema.sql`).

**Maßnahmen:**
*   `ping-service` muss `V1__init.sql` enthalten.
*   `spring.flyway.enabled=true` in `application.yml`.

---

## Zusammenfassung der Aufgaben für den Senior Backend Developer

1.  **Persistenz:** JPA für `PingEntity` verwenden.
2.  **Security:** Auf das Modul `infrastructure/security` warten (Architect erstellt Skeleton) ODER direkt im `ping-service` implementieren und später refaktorieren (bevorzugt: Architect erstellt Modul sofort).
3.  **Messaging:** Kafka vorerst ignorieren.
4.  **Flyway:** `V1__init.sql` im `ping-service` erstellen.