# ALIGNMENT_REVIEW_SUMMARY_v1.0

**Projekt:** Reconcilix  
**Dokumenttyp:** Konsolidiertes Architecture Conformance Assessment  
**Review-Rolle:** ED  
**Status:** Entwurf zur Prüfung durch LA  
**Version:** 1.0  
**Datum:** 2026-07-24

---

## 1. Auftrag und Zielsetzung

Dieses Gutachten konsolidiert die Alignment Reviews 001 bis 009 und bewertet zusätzlich den aktuellen Projektstand nach `WP2-007_Transaction_Boundary_and_Repository_Coordination` unmittelbar gegen die freigegebene beziehungsweise maßgebliche Architektur- und Methodik-Baseline.

Gegenstand ist damit nicht nur die rückblickende Zusammenfassung einzelner Work Packages. Bewertet wird der gegenwärtige Architekturzustand von Reconcilix als zusammenhängendes System:

- fachliches Domain Model,
- Application Boundary und produktiver Request Flow,
- Runtime und Composition,
- logische und technische Persistenz,
- Rehydration und Transaction Boundary,
- methodische Anschlussfähigkeit,
- Test- und Dokumentationsstruktur,
- Eignung als Grundlage für das weitere Alignment und WP3.

Das Dokument soll drei Fragen beantworten:

1. Welche Architekturentscheidungen sind bereits stabil umgesetzt?
2. Welche Abweichungen bestehen zwischen aktuellem Code und aktueller Baseline?
3. Welche Arbeiten sind vor der nächsten funktionalen Ausbauphase zu priorisieren?

---

## 2. Bewertungsgrundlage

### 2.1 Konsolidierte Einzelreviews

| Review | Liefergegenstand | Kernergebnis |
|---|---|---|
| `ALIGNMENT_REVIEW_001` | WP1-001A Domain Foundation, WP1-001B Application Boundary | Solide Foundation; substanzielles fachliches Alignment erforderlich |
| `ALIGNMENT_REVIEW_002` | WP1-002 Application Flow, WP1-002A Duplicate Candidate Fix | Produktiver Flow und Schichtung grundsätzlich stabil |
| `ALIGNMENT_REVIEW_003` | WP2-001 Runtime Infrastructure | Runtime-Schichtung stabil |
| `ALIGNMENT_REVIEW_004` | WP2-002 Composition Root | Zentralisierte Infrastrukturverdrahtung stabil |
| `ALIGNMENT_REVIEW_005` | WP2-003 Persistence Foundation | Technische Persistenzgrundlage stabil |
| `ALIGNMENT_REVIEW_006` | WP2-004 Schema and Migrations | Reproduzierbare Migrationsarchitektur stabil |
| `ALIGNMENT_REVIEW_007` | WP2-005 Relational Repositories and Data Mapper | Repository-/Mapper-Grundstruktur technisch tragfähig |
| `ALIGNMENT_REVIEW_008` | WP2-006 Rehydration und FIX1 | Rehydrationsmechanik technisch tragfähig |
| `ALIGNMENT_REVIEW_009` | WP2-007 Transaction Boundary and Repository Coordination | Transaktionsmechanik stabil; aktuelle Baseline-Abweichungen werden im Gesamtfluss sichtbar |

### 2.2 Aktuelle Baseline

- `ADR002_SOURCE_DELIVERY_MODEL_V4.md`
- `DM001_Domain_Model_v0.5_FINAL.md`
- `DM002_Persistence_Model_v0.5_ED-LA.md`
- `ME001_Interpretation_Properties_and_Vocabulary_Matching_Patterns_v0.2_ALPHA.md`
- `ME002_Interpretation_Driven_Reconciliation_v0.6_DRAFT.md`
- `ROADMAP_MATCHING.md`

### 2.3 Aktueller Projektstand

Geprüft wurde das Projekt-ZIP:

```text
reconcile_ADR001.WP2_20260724_1
```

Der Stand enthält unter anderem:

- Domain- und Application-Code,
- OpenRefine-Integration,
- Runtime und Composition Root,
- Persistence Foundation,
- Migrationen,
- relationale Repositorys und Data Mapper,
- Rehydration,
- Transaction Boundary,
- Tests,
- ADR-, DM-, ME- und Work-Package-Dokumentation,
- Vorbereitungsdokumente für WP3.

### 2.4 Bewertungsprinzip

Für dieses Gesamtgutachten gilt folgende Rangfolge:

```text
aktuelle akzeptierte Baseline
        ↓
aktueller Projektcode
        ↓
Einzelreviews als historische und analytische Evidenz
```

Wo ältere Einzelreviews eine positive Bewertung aussprechen, die mit der aktuellen Baseline oder dem heutigen Gesamtfluss nicht mehr vereinbar ist, hat die aktuelle Direktprüfung Vorrang. Dies betrifft insbesondere die Aggregate- und Repository-Grenze sowie die nachträglich durch ADR002 eingeführte Provenienzstruktur.

---

## 3. Executive Summary

Reconcilix besitzt nach Abschluss von WP2-007 eine **technisch bemerkenswert konsistente und evolutionsfähige Architektur**. Die Implementierung zeigt über alle Schichten hinweg ein hohes Maß an Disziplin:

- Domain, Application und Infrastructure sind klar getrennt.
- Der produktive OpenRefine-Flow ist über Commands, Mapper, Application Service und Gateway strukturiert.
- Legacy-Komponenten werden durch einen Adapter gekapselt.
- Runtime-Erzeugung und Composition Root sind klar abgegrenzt.
- Die Persistenz wurde schrittweise und kontrolliert eingeführt.
- Migrationen, Data Mapper, Repositorys, Rehydration und Transaktionssteuerung folgen einer nachvollziehbaren Entwicklungslinie.
- Die Transaktionsgrenze liegt korrekt im Application Layer.
- Der nichtpersistente Laufzeitpfad bleibt erhalten.
- Die Codebasis ist grundsätzlich gut testbar und für weitere Candidate Provider vorbereitet.

Die zentrale Schwäche liegt **nicht** in der technischen Schichtung. Sie liegt im zeitlichen Drift zwischen einer früher implementierten fachlichen Struktur und der inzwischen weiterentwickelten Baseline aus ADR002, DM001 v0.5 und DM002 v0.5.

Die wichtigsten offenen Alignment-Themen sind:

1. `SourceSystem` und `SourceDelivery` sind im produktiven Domain- und Persistenzfluss noch nicht integriert.
2. `SourceValue.sourceDeliveryId` fehlt, sodass Immutable Provenance nicht umgesetzt ist.
3. `ReconciliationResult` wird technisch und in den Repository-Ports weiterhin wie ein eigenständiges Aggregate behandelt, obwohl DM001 es innerhalb des `SourceValue` Aggregate verortet.
4. Der gespeicherte Originalwert wird durch `trim()` verändert.
5. Candidate Provider, tatsächlicher Candidate Entity Type und Target Vocabulary werden semantisch noch nicht korrekt transportiert.
6. `InterpretationProperty`, `VocabularyMatchingPattern`, `ContextItem` und die produktive `MatchDecision` sind noch nicht vollständig in den Runtime-Flow integriert.
7. Die iterative Interpretation nach ME002 ist als Architektur angelegt, aber noch nicht als vollständige Fähigkeit implementiert.

### Gesamturteil

> **Reconcilix ist technisch reif genug für die nächste Entwicklungsphase, fachlich jedoch noch nicht vollständig baseline-konform.**

Empfohlen wird daher kein Neuaufbau, sondern ein klar begrenztes Alignment-Paket vor der funktionalen Erweiterung von WP3. Die vorhandenen Schichten, Ports, Mapper, Runtime- und Transaktionsmechanismen sollten erhalten bleiben. Das Alignment ist überwiegend additiv und refaktorisierend.

**Gesamtbewertung:** 🟡 **hoher Architektur-Reifegrad bei zwingendem Domain- und Provenienz-Alignment vor weiterem Capability-Ausbau**

---

## 4. Architekturüberblick des aktuellen Systems

Der aktuelle produktive Pfad lässt sich vereinfacht wie folgt darstellen:

```text
OpenRefine Request
    ↓
OpenRefineRequestMapper
    ↓
ReconciliationCommand
    ↓
ReconciliationApplicationService
    ↓
CandidateDiscoveryGateway
    ↓
LegacyCandidateDiscoveryAdapter
    ↓
Provider / ReconciliationStore / xTree
    ↓
ReconciliationOutcome
    ↓
OpenRefineResponseMapper
```

Bei aktivierter Persistenz wird dieser Pfad ergänzt durch:

```text
ReconciliationApplicationService
    ↓
TransactionManager.begin()
    ↓
SourceValueRepository.save()
    ↓
ReconciliationResultRepository.save()
    ↓
TransactionManager.commit()
```

Die Infrastruktur wird zentral über den `ReconciliationCompositionRoot` verdrahtet. `RuntimeFactory` und `RuntimeContext` kapseln Laufzeitabhängigkeiten. Die relationale Speicherung wird über Data Mapper und PDO-basierte Repositorys realisiert.

Diese Gesamtstruktur ist grundsätzlich kohärent. Die problematischen Punkte entstehen dort, wo der fachliche Objektgraph der aktuellen DM001-Baseline nicht mehr mit den historisch entstandenen Repository- und Erzeugungsgrenzen übereinstimmt.

---

## 5. Bewertung der Domain-Architektur

### 5.1 Stärken

#### Persistence Ignorance

Die Domain-Klassen kennen weder PDO noch SQL, HTTP, OpenRefine oder konkrete Provider. Dies ist eine der stabilsten Architekturentscheidungen des Projekts und entspricht DM002.

#### Explizite Fachobjekte

Die Interpretation-and-Reconciliation-Struktur wird durch eigene Domain Objects sichtbar gemacht:

- `SourceValue`
- `InterpretationGraph`
- `InterpretationNode`
- `ReconciliationResult`
- `CandidateItem`
- `MatchDecision`

Damit wird Reconciliation nicht auf einen bloßen Lookup reduziert. Diese Modellierung ist eine wesentliche fachliche Stärke von Reconcilix.

#### Initial Scope ist bewusst begrenzt

Genau ein Whole-Value-Graph und eine initiale Root Node sind mit der ersten Implementierungsphase vereinbar. Der begrenzte Scope verhindert, dass bereits im ersten Schritt komplexe Graphalgorithmen oder mehrere Entity Types erzwungen werden.

#### Domain-Invarianten sind grundsätzlich vorhanden

Die Domain Foundation schützt unter anderem:

- nicht leere Werte,
- gültige Spans,
- Root-Level,
- eindeutige Candidate URIs pro Result,
- Candidate-Auswahl innerhalb desselben Results,
- Score- und Rank-Grenzen.

### 5.2 Zentrale Abweichungen

#### Source Provenance fehlt

Die aktuelle Baseline verlangt:

```text
SourceSystem
    ↓
SourceDelivery
    ↓
SourceValue
```

Im produktiven Domain Model fehlen weiterhin:

- `SourceSystem` als Domain Aggregate,
- `SourceDelivery` als Domain Aggregate,
- `DeliveryChannel` als Value Object,
- die verpflichtende und unveränderliche `sourceDeliveryId` im `SourceValue`.

Die vorhandene Klasse `src/SourceSystem/SourceSystemFactory.php` ist kein Ersatz für das in DM001 definierte Domain Aggregate. Sie gehört zur älteren Systemlogik und bildet die neue Provenienzstruktur nicht vollständig ab.

**Bewertung:** 🔴 Anpassung erforderlich

#### Aggregate-Grenze von SourceValue

DM001 definiert `SourceValue` als Aggregate Root, das den vollständigen Interpretations- und Reconciliation-Zustand umfasst. Im aktuellen Code und in den Repository-Ports werden `SourceValue` und `ReconciliationResult` getrennt behandelt.

Technisch getrennte Mapper und Tabellen sind zulässig. Ein öffentliches `ReconciliationResultRepository` signalisiert jedoch eine eigenständige Aggregate Root, die DM001 nicht vorsieht.

**Bewertung:** 🔴 Architekturentscheidung muss umgesetzt oder Baseline explizit geändert werden

#### Fachliche Beziehungen hängen an technischen IDs

Ein `ReconciliationResult` wird erst nach dem Speichern des `SourceValue` erzeugt, weil die `InterpretationNode` zuvor keine persistente ID besitzt. Die technische ID bestimmt damit die Erzeugungsreihenfolge fachlicher Objekte.

Das ist ein Indikator dafür, dass fachliche Identität und Datenbankidentität noch nicht sauber genug getrennt sind.

**Bewertung:** 🟡 bis 🔴, abhängig von der gewählten Aggregate-Repräsentation

#### Finale MatchDecision

Die Baseline erlaubt mehrere Entscheidungen, aber höchstens eine fachlich gültige finale Entscheidung. Diese Invariante ist noch nicht vollständig abgesichert.

**Bewertung:** 🟡 Ergänzung erforderlich

#### ContextItem

`ContextItem` gehört zur Baseline, ist im aktuellen produktiven Domain-Flow aber noch nicht integriert. Für Phase 1 ohne Kontextverarbeitung ist dies nachvollziehbar; für Phase 2 wird es zu einer zentralen Voraussetzung.

**Bewertung:** 🟡 geplanter Ausbau

### 5.3 Teilurteil Domain

Die Domain-Architektur ist **konzeptionell stark und technisch sauber isoliert**, aber noch nicht vollständig auf DM001 v0.5 angehoben.

**Reifegrad:** 4 von 5  
**Alignment:** 🟡

---

## 6. Bewertung des Application Layer

### 6.1 Stärken

#### Application Service als Orchestrator

Der `ReconciliationApplicationService` koordiniert den Use Case, ohne Transport- oder Infrastrukturdetails zu übernehmen.

#### Candidate Discovery Port

`CandidateDiscoveryGateway` ist eine stabile Abstraktion. Sie ermöglicht später:

- xTree/MCT,
- QLever,
- Vector Search,
- Lobid/GND,
- weitere Provider.

#### Anti-Corruption Layer

Der `LegacyCandidateDiscoveryAdapter` schützt den neuen Application-/Domain-Kern vor dem älteren Query- und Provider-Modell.

#### Dünne Transportgrenze

Request- und Response-Mapping sind von der fachlichen Verarbeitung getrennt. OpenRefine bleibt Client, nicht Domain-Modell.

#### Duplicate Candidate Fix

Doppelte Candidate URIs werden vor Eintritt in das Domain Model entfernt. Diese Verantwortung liegt an einer geeigneten Grenze.

### 6.2 Abweichungen

#### Originalwert wird getrimmt

Der Application Service übergibt `trim($command->sourceValue)` an den Domain-Erzeugungspfad. Das widerspricht der Baseline-Anforderung an den unveränderten Original Value.

Neben der Provenienz betrifft dies auch die korrekte Berechnung von Spans und `sourceFragment`.

**Bewertung:** 🔴 kurzfristig korrigieren

#### SourceDelivery wird nicht koordiniert

Der Application Command enthält keine belastbare Referenz auf eine bestehende `SourceDelivery` und erzeugt auch keine neue Delivery. Damit kann der Application Service die aggregateübergreifende Vollständigkeitsregel aus DM001 nicht erfüllen.

**Bewertung:** 🔴 zentrale Alignment-Aufgabe

#### Target Vocabulary Fallback

`targetVocabularyUri` fällt auf `preferredEntityTypeUri` zurück. Erwarteter Entity Type und fachliches Zielvokabular sind unterschiedliche Konzepte.

**Bewertung:** 🔴 semantisch falsch

#### Candidate Entity Type

Der tatsächliche Entity Type des Candidates wird nicht aus dem Discovery-Ergebnis übernommen, sondern aus der Erwartung des Requests abgeleitet.

Dies verhindert die methodisch relevante Erkennung von `NOT_TARGET_ENTITY_TYPE` beziehungsweise falscher semantischer Klasse.

**Bewertung:** 🔴 korrigieren

#### Candidate Provider

Der Discovery-Vertrag liefert keine eindeutige `candidateProviderUri`. Dadurch bleibt die Candidate-Herkunft unvollständig.

**Bewertung:** 🟡 bis 🔴 vor Integration mehrerer Provider

### 6.3 Teilurteil Application

Der Application Layer ist strukturell sehr gut. Die offenen Punkte sind semantische Mapping- und Use-Case-Probleme, keine Schichtungsprobleme.

**Reifegrad:** 4,5 von 5  
**Alignment:** 🟡

---

## 7. Runtime, Composition und Infrastruktur

### 7.1 Runtime Infrastructure

`RuntimeContext` kapselt Laufzeitinformationen. `RuntimeFactory` erzeugt die für eine Verarbeitungseinheit erforderlichen Services. Domain- und Runtime-Verantwortung bleiben getrennt.

### 7.2 Composition Root

Der `ReconciliationCompositionRoot` ist die zentrale Verdrahtungsstelle. Er erzeugt Controller, Provider, Factories, Persistence-Komponenten und Adapter, ohne fachliche Regeln zu implementieren.

### 7.3 Konfiguration

Die Persistenz ist konfigurierbar und der nichtpersistente Flow bleibt grundsätzlich funktionsfähig. Positiv ist die All-or-nothing-Anforderung für Transaction Manager und Repositorys.

### 7.4 Projektzustand und Konfigurationsvollständigkeit

Beim Testlauf im entpackten Projektstand liefen die ersten Domain- und Application-Tests erfolgreich. Der Composition-Root-Test konnte in der gelieferten Umgebung jedoch nicht ausgeführt werden, weil `config/database.php` fehlt und die Konfigurationsklasse diese Datei als erforderlich behandelt.

Dies ist kein Nachweis eines fachlichen Fehlers. Es zeigt aber eine Reproduzierbarkeitslücke des gelieferten Projektpakets:

- entweder muss eine nichtgeheime Beispielkonfiguration enthalten sein,
- oder der Test muss eine isolierte Testkonfiguration erzeugen,
- oder optionale Persistenz darf bei fehlender Datenbankkonfiguration nicht bereits den Composition-Test blockieren.

### 7.5 Historische Dateien im produktiven Source Tree

Im Projekt befinden sich zahlreiche datierte Sicherungskopien direkt unter `src/`, beispielsweise:

```text
ReconciliationApplicationService_20260718.php
ReconciliationCompositionRoot_20260720_2.php
TransactionManager_20260720.php
Mapper/20260720_0/
Repository/20260720/
```

Diese Dateien erhöhen das Risiko von:

- Verwechslungen,
- versehentlicher Autoload-Aufnahme,
- erschwerter Codeanalyse,
- unklarer Source-of-Truth,
- unnötiger Wartungslast.

Versionierung sollte durch Git erfolgen. Historische Implementierungsstände gehören nicht in den aktiven Source Tree.

### 7.6 Teilurteil Infrastruktur

Runtime und Composition sind architektonisch stark. Verbesserungsbedarf besteht bei der Liefer- und Repository-Hygiene sowie der reproduzierbaren Testkonfiguration.

**Reifegrad:** 4,5 von 5  
**Alignment:** 🟢 mit technischen Härtungsmaßnahmen

---

## 8. Bewertung der Persistenzarchitektur

### 8.1 Persistence Foundation

Die lazy initialisierte PDO-Verbindung und der abstrahierte `TransactionManager` sind sauber von der Domäne getrennt. Eine globale Verbindung wird vermieden.

### 8.2 Migrationen

Die Migrationen sind:

- forward-only,
- versioniert,
- mit Prüfsummen geschützt,
- über eine Registry verwaltet,
- gegen parallele Ausführung gesperrt,
- explizit über CLI ausführbar.

Diese Lösung ist betrieblich und architektonisch überzeugend.

### 8.3 Data Mapper

Die Mapper kapseln die Übersetzung zwischen relationaler Darstellung und Domain Objects. Fachlogik wird nicht in SQL oder Mapper verschoben.

### 8.4 Repositorys

Die Repository-Ports liegen im Application Layer, die PDO-Implementierungen in Infrastructure. Dies entspricht Ports-and-Adapters.

Problematisch ist nicht die technische Repository-Implementierung, sondern die fachliche Schnittbildung:

```text
SourceValueRepository
ReconciliationResultRepository
```

Sie reflektiert nicht die aktuelle `SourceValue`-Aggregate-Grenze aus DM001.

### 8.5 Rehydration

Die Rehydration liegt an der richtigen Stelle: Repository-/Mapper-Schicht. FIX1 zeigt, dass Implementierungsfehler korrigiert werden können, ohne die Schichten neu zu ordnen.

Für das Baseline-Alignment muss die Rehydration später den vollständigen `SourceValue`-Aggregate-Zustand rekonstruieren können.

### 8.6 Transaction Boundary

WP2-007 ist eine starke technische Lieferung:

- Transaktion pro persistentem Use Case,
- Begin/Commit/Rollback im Application Service,
- gemeinsame PDO-Verbindung,
- keine Transaktionssteuerung in Repositorys,
- Rollback bei Exception,
- ursprüngliche Exception bleibt erhalten,
- Teilkonfiguration wird zurückgewiesen.

Die Transaction Boundary ist technisch richtig, koordiniert aktuell jedoch zwei Repositorys für Teile eines fachlich einzigen Aggregates. Nach dem Aggregate-Alignment kann die Mechanik erhalten bleiben, während die Repository-Koordination angepasst wird.

### 8.7 Teilurteil Persistenz

Die technische Persistenzarchitektur ist einer der reifsten Bereiche des Projekts. Die wichtigste offene Arbeit ist die Anpassung an die inzwischen präzisierte fachliche Aggregate- und Provenienzstruktur.

**Reifegrad:** 4,5 von 5  
**Alignment:** 🟡 aufgrund fachlicher Modellabweichungen

---

## 9. Bewertung von ME001

ME001 trennt zwei Klassifikationsebenen, die in vielen Reconciliation-Systemen vermischt werden:

- intrinsische Eigenschaften einer Interpretation (`InterpretationProperty`),
- relationale Muster eines Reconciliation-Ergebnisses (`VocabularyMatchingPattern`).

Diese Trennung ist fachlich überzeugend und erhöht die Erklärbarkeit des Systems.

### Aktueller Implementierungsstand

- Die Domain-Struktur ist teilweise vorbereitet.
- `InterpretationProperty` wird im produktiven Flow noch nicht vergeben.
- `VocabularyMatchingPattern` ist teilweise als Property vorbereitet, aber noch nicht systematisch produktiv gesetzt.
- kontrollierte URI-Werte und spätere xTree-Publikation sind konzeptionell vorgesehen.

### Bewertung

ME001 ist als Working Draft bewusst evaluativ. Die fehlende vollständige Implementierung ist kein Architekturfehler, solange das nächste Work Package nicht vorgibt, Phase 1 bereits abgeschlossen zu haben.

**Reifegrad Methodik:** 4 von 5  
**Implementierungsabdeckung:** 2 bis 3 von 5

---

## 10. Bewertung von ME002

ME002 formuliert den eigentlichen Innovationskern von Reconcilix:

> Interpretation before Reconciliation.

Der aktuelle Code implementiert den ersten linearen Pfad:

```text
SourceValue
→ Whole-Value InterpretationGraph
→ Root InterpretationNode
→ Candidate Discovery
→ ReconciliationResult
→ CandidateItems
```

Noch offen sind:

- mehrere interpretierbare Spans,
- weitere beziehungsweise abgeleitete Nodes,
- Zuweisung von Interpretation Properties,
- Strategy Selection anhand fachlicher Beobachtungen,
- Result Quality Evaluation,
- iterativer Strategie- oder Interpretationswechsel,
- Vocabulary Matching Pattern,
- produktive Match Decision,
- Manual-Review-/Needs-Context-Pfade.

### Bewertung

Die Architektur ist für diese Erweiterungen grundsätzlich vorbereitet. Besonders wichtig ist, die iterative Methodik nicht vorschnell als starre technische Pipeline zu implementieren. Die Roadmap betont zu Recht Matching Strategies und austauschbare Techniques.

**Reifegrad Methodik:** 4 von 5  
**Implementierungsabdeckung Phase 1:** etwa 3 von 5

---

## 11. Bewertung der Roadmap

Die Roadmap ist weiterhin überwiegend tragfähig. Ihre Phasenfolge entspricht der Architektur:

1. Interpretation-driven Core
2. Context-aware Vector-assisted Reconciliation
3. GND via Lobid
4. Multi-vocabulary Reconciliation
5. Adaptive Matching Strategies
6. Extended Domain Capabilities

### Aktualisierungsbedarf

Die Roadmap wurde parallel zu ADR001 erstellt und nennt in ihrer Current Baseline noch nicht vollständig:

- `SourceSystem`,
- `SourceDelivery`,
- `DeliveryChannel`,
- die verpflichtende `sourceDeliveryId`.

Phase 1 sollte künftig ausdrücklich erst als abgeschlossen gelten, wenn das ADR002-Alignment umgesetzt ist.

Zusätzlich sollte zwischen drei Statusarten unterschieden werden:

- Architektur definiert,
- technisch implementiert,
- fachlich evaluiert.

Dies verhindert, dass eine vorhandene Klasse oder Tabelle vorschnell als abgeschlossene Capability bewertet wird.

---

## 12. Konsolidierte Architekturstärken

### 12.1 Klare Dokumenthierarchie

```text
ADR
→ DM
→ ME
→ WP
→ Alignment Review
```

Diese Hierarchie ist außergewöhnlich wertvoll. Sie ermöglicht es, Architekturentscheidungen, Fachmodell, Methodik und Implementierung getrennt zu diskutieren.

### 12.2 Evolution statt Big Bang

Die Persistenz wurde nicht in einem großen Paket eingeführt, sondern kontrolliert in Foundation, Migrationen, Mapper, Repositorys, Rehydration und Transaction Boundary zerlegt.

### 12.3 Fachliche Erklärbarkeit

InterpretationGraph, InterpretationNode, CandidateItem, Matching Pattern und Match Decision schaffen eine Grundlage für Explainable Reconciliation.

### 12.4 Provider-Unabhängigkeit

Candidate Discovery ist über Ports abstrahiert. Dies ist Voraussetzung für QLever, Vector Search, Lobid/GND und Multi-Vocabulary-Reconciliation.

### 12.5 Reproduzierbare Evaluation als Leitidee

README und Roadmap verbinden Softwareentwicklung mit methodischer Evaluation. Das ist für kulturhistorische Fachdaten besonders angemessen.

### 12.6 Rollen- und Reviewstruktur

Die Trennung zwischen PL, LA und ED sowie der Reviewfluss

```text
ED → LA Review → ED Umsetzung
```

unterstützt Architekturqualität, solange Verantwortlichkeiten und Entscheidungsstatus in den Dokumenten eindeutig bleiben.

---

## 13. Konsolidierte Alignment-Themen

| ID | Thema | Schweregrad | Ursprung | Status |
|---|---|---:|---|---|
| AS-01 | SourceSystem/SourceDelivery fehlen im produktiven Domain Flow | hoch | Baseline-Erweiterung ADR002 | offen |
| AS-02 | `SourceValue.sourceDeliveryId` fehlt | hoch | Baseline-Erweiterung ADR002/DM001 | offen |
| AS-03 | SourceValue/ReconciliationResult Aggregate-Grenze | hoch | historisches Domain Design | offen |
| AS-04 | Original Value wird getrimmt | hoch | Application Mapping | offen |
| AS-05 | Fachbeziehungen hängen an technischen DB-IDs | mittel-hoch | Persistenz-/Domain-Kopplung | offen |
| AS-06 | `candidateProviderUri` fehlt beziehungsweise ist überholt benannt | mittel | Candidate-Semantik | offen |
| AS-07 | tatsächlicher Candidate Entity Type fehlt | mittel | Discovery Contract | offen |
| AS-08 | Target Vocabulary fällt auf Entity Type zurück | mittel | Application Mapping | offen |
| AS-09 | höchstens eine finale MatchDecision nicht abgesichert | mittel | Domain-Invariante | offen |
| AS-10 | ContextItem nicht integriert | mittel | geplanter Ausbau | offen |
| AS-11 | InterpretationProperty nicht produktiv integriert | mittel | ME001-Ausbau | PRE_WP3 geplant |
| AS-12 | VocabularyMatchingPattern nicht produktiv integriert | mittel | ME001-Ausbau | PRE_WP3 geplant |
| AS-13 | iterativer ME002-Flow fehlt | mittel | Capability-Ausbau | später |
| AS-14 | Testpaket benötigt lokale `database.php` | niedrig-mittel | Lieferreproduzierbarkeit | offen |
| AS-15 | historische PHP-Kopien im aktiven Source Tree | niedrig-mittel | Repository-Hygiene | offen |

---

## 14. Architektur-Reifegrad

| Bereich | Reifegrad | Begründung |
|---|---:|---|
| Architekturprinzipien | 5/5 | klar dokumentiert und weitgehend durchgehalten |
| Domain-Schichtung | 5/5 | frei von Infrastrukturkopplung |
| Domain-Baseline-Alignment | 3/5 | ADR002 und Aggregate-Grenze noch offen |
| Application Architecture | 4,5/5 | sehr gute Orchestrierung; semantische Mappings offen |
| Runtime/Composition | 4,5/5 | klar strukturiert; Konfigurationshärtung sinnvoll |
| Persistenztechnik | 4,5/5 | Migration, Mapper, Rehydration, Transaktion sehr reif |
| Persistenz-Baseline-Alignment | 3/5 | SourceDelivery und Aggregate-Struktur fehlen |
| ME001-Implementierung | 2,5/5 | konzeptionell vorbereitet, produktiv noch unvollständig |
| ME002-Implementierung | 3/5 | initialer Pfad vorhanden, Iteration fehlt |
| Testbarkeit | 4/5 | gute Einzeltests; reproduzierbares Gesamtsetup verbessern |
| Dokumentation | 4,5/5 | sehr umfangreich; Source-of-Truth und Archivierung weiter schärfen |
| Erweiterbarkeit | 5/5 | Provider-, Strategy- und Persistence-Erweiterung gut vorbereitet |

### Gesamt-Reifegrad

**4 von 5 — architektonisch fortgeschritten, vor Capability-Ausbau fachlich zu konsolidieren**

---

## 15. Risiken

### 15.1 Domain/Baseline Drift

Werden WP3-Funktionen auf der aktuellen Struktur aufgebaut, verfestigen sich die fehlende Provenienz und die falsche Aggregate-Grenze. Der spätere Refactoring-Aufwand steigt überproportional.

### 15.2 Semantische Vermischung

Die Begriffe

- SourceSystem,
- Candidate Provider,
- Target Vocabulary,
- preferred Entity Type,
- Delivery Channel

müssen strikt getrennt bleiben. Eine Vermischung beeinträchtigt Evaluation, Persistenz und spätere Multi-Provider-Verarbeitung.

### 15.3 Methodik wird zu früh technisch verengt

InterpretationProperty und VocabularyMatchingPattern dürfen nicht zu bloßen technischen Flags werden. Sie müssen kontrolliert, URI-basiert und anhand realer Expertendaten validiert bleiben.

### 15.4 Externe Services vor stabiler Domain Integration

Vector Search oder Lobid sollten erst integriert werden, wenn Candidate Provider, Target Vocabulary, ContextItem und Provenienz sauber modelliert sind. Andernfalls werden externe Unterschiede in instabile interne Verträge eingebacken.

### 15.5 Test- und Lieferreproduzierbarkeit

Fehlende Beispielkonfigurationen und historische Dateien im aktiven Source Tree können bei weiteren Beteiligten zu abweichenden Ergebnissen führen.

---

## 16. Priorisierte nächste Schritte

### Priorität A — Baseline Alignment vor WP3

#### A1 Provenance Domain Integration

Implementieren:

- `SourceSystem` Aggregate,
- `SourceDelivery` Aggregate,
- `DeliveryChannel` Value Object,
- verpflichtende `SourceValue.sourceDeliveryId`,
- Application Service zur Koordination vollständiger Deliveries,
- Repositorys, Mapper, Migrationen und Rehydration,
- Immutable-Provenance-Tests.

#### A2 SourceValue Aggregate Alignment

- Entscheidung aus DM001 technisch umsetzen.
- `ReconciliationResultRepository` als öffentliches Aggregate-Repository auflösen oder die Baseline durch LA ausdrücklich revidieren.
- vollständigen SourceValue-Zustand über den Aggregate Root zugänglich und rehydrierbar machen.
- fachliche Identitäten nicht von erst nachträglich vergebenen DB-IDs abhängig machen.

#### A3 Original Value

- `trim()` aus dem Persistenz-/Domain-Erzeugungspfad entfernen.
- normalisierte Werte ausschließlich als abgeleitete Interpretation behandeln.
- Byte-/String-Identität testen.

#### A4 Candidate Semantics

- `candidateProviderUri` im Discovery Contract ergänzen,
- tatsächlichen Candidate Entity Type liefern,
- `targetVocabularyUri` als eigenes fachliches Feld behandeln,
- Fallback auf `preferredEntityTypeUri` entfernen.

### Priorität B — Domain-Invarianten und Härtung

- höchstens eine gültige finale MatchDecision,
- valide Node-/Result-Zuordnung,
- Fehlerfälle beider Repositorys und Commit/Rollback ergänzend testen,
- Datenbank-Integrationstest über vollständige Transaktion,
- reproduzierbare Testkonfiguration bereitstellen,
- historische Source-Dateien aus aktivem Code entfernen.

### Priorität C — Methodik / PRE-WP3

- `InterpretationProperty` integrieren,
- `VocabularyMatchingPattern` integrieren,
- kontrollierte URI-Werte und Registry-Strategie definieren,
- produktive `MatchDecision` ergänzen,
- Result Quality Evaluation und lineare Node-Ableitung schrittweise umsetzen.

### Priorität D — Externe Candidate Discovery

Erst nach A und wesentlichen Teilen von B/C:

- xTree Candidate Discovery Adapter,
- QLever beziehungsweise Vector Search API,
- Lobid/GND,
- Context-aware Ranking.

---

## 17. Empfehlung zur Paketbildung

Ein zusammenhängendes Alignment-Paket ist einem ungeordneten Refactoring vorzuziehen.

Vorgeschlagene Struktur:

```text
POST-WP2-BASELINE-ALIGNMENT

WP-A1  Provenance Domain Integration
WP-A2  SourceValue Aggregate Alignment
WP-A3  Persistence Schema and Migration Alignment
WP-A4  Repository and Rehydration Alignment
WP-A5  Application Command and Candidate Semantics
WP-A6  Domain Invariants and Regression Tests
WP-A7  Repository Hygiene and Test Reproducibility
```

Danach:

```text
WP3

WP3-001  xTree Candidate Discovery Adapter
WP3-002  Interpretation Property Integration
WP3-003  Vocabulary Matching Pattern Integration
WP3-004  Match Decision and Result Evaluation
WP3-005  Linear Interpretation Iteration
```

Die genaue Nummerierung bleibt Aufgabe von PL/LA. Entscheidend ist die Reihenfolge: Baseline-Alignment vor Ausbau der methodischen und externen Fähigkeiten.

---

## 18. Freigabeempfehlung nach Bereichen

| Bereich | Empfehlung |
|---|---|
| Domain/Application-Schichtung | freigeben und stabil halten |
| Candidate Discovery Port | freigeben und erweitern |
| Legacy Adapter | freigeben als Anti-Corruption Layer |
| Runtime und Composition Root | freigeben |
| Persistence Foundation | freigeben |
| Migration Framework | freigeben |
| Data-Mapper-Ansatz | freigeben |
| Rehydrationsmechanik | freigeben, nach Aggregate-Alignment anpassen |
| Transaction Boundary | freigeben, Repository-Koordination anpassen |
| aktuelle Aggregate-/Repository-Grenze | nicht als endgültige Baseline freigeben |
| aktueller Provenienzfluss | nicht freigeben |
| ME001/ME002 als vollständige Capability | noch nicht als umgesetzt kennzeichnen |

---

## 19. Schlussgutachten

Reconcilix verfügt nach WP2-007 über eine außergewöhnlich sorgfältig aufgebaute technische Basis. Besonders hervorzuheben sind die konsequente Schichtentrennung, der Application-Port für Candidate Discovery, die kontrollierte Einführung der Persistenz, der explizite Composition Root und die saubere Transaction Boundary.

Das Projekt zeigt damit bereits Eigenschaften einer langfristig wartbaren Plattform und nicht nur eines einzelnen Reconciliation-Endpunkts. Die Architektur ist geeignet, weitere Vokabulare, Provider, Matching Techniques und Evaluationsverfahren aufzunehmen.

Die identifizierten Abweichungen sind ernst zu nehmen, stellen aber keinen Grund für einen Neuaufbau dar. Sie erklären sich überwiegend aus der zeitlichen Reihenfolge der Entwicklung: Der ursprüngliche Reconciliation-Kern wurde implementiert, bevor ADR002 und die v0.5-Fassungen von DM001 und DM002 die Provenienz- und Aggregate-Struktur präzisiert haben.

Die richtige Konsequenz ist daher ein gezieltes Alignment:

- Provenienz ergänzen,
- Aggregate-Grenzen korrigieren,
- Originalwert schützen,
- Candidate-Semantik präzisieren,
- methodische Objekte anschließend produktiv integrieren.

> **Gesamturteil:** Reconcilix besitzt eine tragfähige, hochwertige und erweiterbare Architektur. Der technische Kern kann als stabil angesehen werden. Vor dem Einstieg in die nächste größere Capability-Phase ist jedoch ein verbindliches Domain- und Persistenz-Alignment an ADR002, DM001 v0.5 und DM002 v0.5 erforderlich.

Nach Durchführung dieses Alignment-Pakets ist Reconcilix aus Architektursicht gut vorbereitet für:

- die vollständige Umsetzung von ME001 und ME002,
- die xTree-/QLever-Integration,
- context-aware Candidate Discovery,
- Vector Search,
- Lobid/GND,
- Multi-Vocabulary-Reconciliation.

---

## 20. Reviewauftrag an LA

LA sollte insbesondere folgende Punkte prüfen und entscheiden:

1. Bestätigung der Interpretation der `SourceValue`-Aggregate-Grenze.
2. Bestätigung, dass `ReconciliationResultRepository` als öffentliches Repository aufzulösen ist, sofern DM001 unverändert bleibt.
3. Zielmodell für stabile fachliche Identitäten innerhalb des Aggregate.
4. Abgrenzung und Transaktionsschnitt für `SourceDelivery` und `SourceValue`.
5. Reihenfolge von Baseline-Alignment und PRE-WP3-Paketen.
6. Einstufung von DM002s Bezeichnung einzelner persistierter Bestandteile als „Aggregate“ gegenüber DM001s Aggregate Boundary.
7. Freigabe der vorgeschlagenen Paketbildung.

---

# Document History

| Version | Status | Beschreibung |
|---|---|---|
| 1.0 | Draft ED | Konsolidierte Gesamtbewertung der Alignment Reviews 001–009, der aktuellen Baseline, Roadmap und des Projektstands nach WP2-007 |