# ADR001-WP2-007 – Transaction Boundary and Repository Coordination

**Status:** Draft

**Date:** 2026-07-20

**Work Package:** WP2-007

---

# 1. Context

WP2-003 bis WP2-006 haben die Persistenzarchitektur von Reconcilix
schrittweise aufgebaut.

Die Persistenzschicht unterstützt inzwischen

- relationale Speicherung,
- relationale Rehydration,
- vollständige Aggregate-Rekonstruktion.

Die Speicherung mehrerer Aggregate erfolgt bislang jedoch unabhängig
voneinander.

Für einen fachlichen Reconciliation-Lauf müssen mehrere Aggregate
atomar gespeichert werden.

Hierfür wird eine explizite Transaction Boundary eingeführt.

---

# 2. Decision

Reconcilix führt eine explizite Transaction Boundary auf
Application-Ebene ein.

Die Koordination mehrerer Repository-Aufrufe erfolgt durch einen
Transaction Manager.

Repositorys bleiben ausschließlich für ihre jeweiligen Aggregate
verantwortlich.

WP2-007 verändert keine Aggregate Boundaries.

Es wird bewusst keine klassische Unit of Work eingeführt.

---

# 3. Architectural Principles

Die bereits definierten Aggregate bleiben unverändert.

## SourceValue Aggregate

```
SourceValue
└── InterpretationGraph
    └── InterpretationNode
```

Persistierung und Rehydration erfolgen weiterhin ausschließlich über

```
RelationalSourceValueRepository
```

---

## ReconciliationResult Aggregate

```
ReconciliationResult
├── CandidateItem
└── MatchDecision
```

Persistierung und Rehydration erfolgen weiterhin ausschließlich über

```
RelationalReconciliationResultRepository
```

Die Transaction Boundary koordiniert mehrere Aggregate.

Sie verändert ihre interne Verantwortung nicht.

---

# 4. Transaction Boundary

Die Transaction Boundary wird ausschließlich vom
Application Service definiert.

Repositorys öffnen oder schließen niemals selbst Transaktionen.

```
Application Service
        │
        ▼
Transaction Manager
        │
        ▼
BEGIN TRANSACTION
        │
        ▼
Repository Operations
        │
        ▼
COMMIT / ROLLBACK
```

---

# 5. Repository Coordination

Repositorys koordinieren ausschließlich ihre eigenen Aggregate.

Die Koordination mehrerer Repositorys erfolgt außerhalb der
Repositorys.

```
Application Service
        │
        ▼
Transaction Manager
        │
        ├──────────────┐
        ▼              ▼
SourceValueRepository
        │
        ▼
ReconciliationResultRepository
```

Repositorys kennen keine Transaktionsgrenzen.

---

# 6. Responsibilities

## Application Service

Der Application Service

- definiert den fachlichen Workflow,
- entscheidet über Beginn und Ende einer Transaktion,
- ruft die beteiligten Repositorys auf.

---

## Transaction Manager

Der Transaction Manager

- beginnt Transaktionen,
- bestätigt erfolgreiche Transaktionen,
- führt Rollbacks aus,
- besitzt keine Fachlogik.

---

## Repository

Repositorys

- persistieren Aggregate,
- rehydrieren Aggregate,
- koordinieren keine Transaktionen,
- kennen keine anderen Repositorys.

---

## Data Mapper

Data Mapper

- lesen relationale Daten,
- schreiben relationale Daten,
- besitzen keine Kenntnis über Transaktionen.

---

# 7. Persistence Flow

## Success

```
Application Service
        │
        ▼
TransactionManager.begin()

        │
        ▼
SourceValueRepository.persist()

        │
        ▼
ReconciliationResultRepository.persist()

        │
        ▼
TransactionManager.commit()
```

---

## Failure

```
Application Service
        │
        ▼
TransactionManager.begin()

        │
        ▼
SourceValueRepository.persist()

        │
        ▼
PersistenceException

        │
        ▼
TransactionManager.rollback()

        │
        ▼
Exception propagated
```

Es verbleiben keine teilweise gespeicherten Aggregate.

---

# 8. Error Handling

Jede Exception innerhalb einer aktiven Transaktion führt zu

```
ROLLBACK
```

Anschließend wird die ursprüngliche Exception erneut geworfen.

Der Transaction Manager übersetzt keine Exceptions.

Die fachliche Interpretation verbleibt in der Application Layer.

---

# 9. Why no Unit of Work?

Reconcilix persistiert Aggregate explizit über Repositorys.

Es existiert kein automatisches Change Tracking innerhalb des
Domain Models.

Eine klassische Unit of Work würde daher

- keine zusätzliche fachliche Konsistenz schaffen,
- zusätzliche Infrastrukturkomplexität einführen,
- Repository-Verantwortlichkeiten verwischen.

Reconcilix entscheidet sich daher bewusst gegen dieses Muster.

---

# 10. Consequences

## Advantages

- atomare Persistierung
- konsistente Datenbank
- klare Verantwortlichkeiten
- Repositorys bleiben unabhängig
- einfache Testbarkeit
- symmetrische Architektur

---

## Disadvantages

- zusätzlicher Infrastrukturbaustein
- Koordination erfolgt zentral
- mehrere Repository-Aufrufe müssen explizit orchestriert werden

---

# 11. Out of Scope

Nicht Bestandteil dieses ADR sind

- Identity Map
- Unit of Work
- Lazy Loading
- ORM
- Change Tracking
- Optimistic Locking
- Event Sourcing
- Distributed Transactions

Diese Themen können in zukünftigen Work Packages betrachtet werden.

---

# 12. Future Evolution

Die Transaction Boundary stellt eine Infrastrukturabstraktion dar.

Sollte Reconcilix künftig

- mehrere Datenbanken,
- Messaging,
- Event Sourcing,
- Outbox Pattern
- oder verteilte Transaktionen

unterstützen,

kann der Transaction Manager ersetzt oder erweitert werden, ohne
Repositorys oder Domain Objects anzupassen.

---

# 13. Revision History

| Revision | Description |
|-----------|-------------|
| Draft | Initial version for LA Review |