# ADR001-WP2-003 – Persistence Foundation **Status:** Accepted **Autor:** ED **Reviewer:** LA **Datum:** 2026-07-20 --- # 1. Kontext Mit den bisherigen Workpackages wurde die technische Laufzeitarchitektur von Reconcilix etabliert. Bereits umgesetzt sind: - WP1 – Domain Integration - WP2-001 – Runtime Architecture - WP2-002 – Composition Root Die Application Layer arbeitet derzeit vollständig ohne relationale Persistenz. Das Domänenmodell gemäß DM001 ist bereits implementiert. Das relationale Zielmodell ist in DM002 definiert. Bevor relationale Repositorys und Data Mapper eingeführt werden, soll zunächst eine stabile technische Persistenzinfrastruktur geschaffen werden. WP2-003 bildet hierfür die Grundlage. --- # 2. Problemstellung Die kommenden Workpackages benötigen - relationale Repositorys, - Data Mapper, - Rehydration, - Transaktionen, - SQL-Schema, - Migrationen. Diese Komponenten dürfen keine direkte Abhängigkeit zu PDO oder konkreten Datenbankverbindungen besitzen. Ebenso soll die Datenbankkonfiguration zentral verwaltet werden. Die technische Datenbankinfrastruktur soll vollständig von der fachlichen Persistierungslogik getrennt bleiben. --- # 3. Entscheidung WP2-003 führt eine eigenständige Persistence Foundation ein. Diese besteht aus - DatabaseConnectionFactory - TransactionManager - PDO-basierter Infrastruktur - Integration in den bestehenden ReconciliationCompositionRoot Die Persistence Foundation stellt ausschließlich technische Infrastruktur bereit. Es erfolgt noch keine Persistierung fachlicher Aggregate. --- # 4. Ziele WP2-003 verfolgt folgende Ziele: - zentrale Verwaltung der Datenbankverbindung - zentrale Verwaltung von Transaktionen - vollständige Kapselung von PDO innerhalb der Infrastructure Layer - Vorbereitung der Repository-Implementierungen - Vorbereitung der Data Mapper - Vorbereitung der SQL-Migrationen --- # 5. Verantwortlichkeiten ## DatabaseConnectionFactory Verantwortlich für - Aufbau der PDO-Verbindung - Konfiguration der PDO-Optionen - Fehlerbehandlung beim Verbindungsaufbau Nicht verantwortlich für - SQL-Ausführung - Repositorys - Transaktionen - Objektmapping --- ## TransactionManager Der TransactionManager bildet den Infrastrukturvertrag (Infrastructure Contract) zwischen Application Layer und Infrastructure Layer. Die Application Layer kennt ausschließlich dieses Interface. Die konkrete Implementierung erfolgt ausschließlich innerhalb der Infrastructure Layer. Verantwortlich für - begin() - commit() - rollback() Nicht verantwortlich für - SQL - Repositorys - Reconciliation - Objektmapping --- ## ReconciliationCompositionRoot Verantwortlich für - Erzeugung der DatabaseConnectionFactory - Erzeugung des TransactionManager - Integration in den bestehenden Objektgraphen Nicht verantwortlich für - Datenbanklogik - SQL - Konfigurationsvalidierung --- ## Configuration Verantwortlich für - Laden der Datenbankkonfiguration - Validierung der Datenbankparameter Nicht verantwortlich für - Aufbau der Datenbankverbindung --- # 6. Lebensdauer der Objekte ## application-scoped Die folgenden Komponenten werden einmal pro aufgebautem Objektgraphen erzeugt: - Configuration - DatabaseConnectionFactory - PDO-Verbindung - TransactionManager Eine PDO-Verbindung wird genau einmal beim Aufbau des jeweiligen Composition Roots erzeugt und innerhalb dieses Objektgraphen wiederverwendet. Es existieren keine globalen Singleton-Verbindungen. Alternative Einstiegspunkte (z. B. CLI, Worker oder Batch-Prozesse) erzeugen jeweils ihren eigenen Composition Root und damit ihre eigene Datenbankverbindung. --- ## processing-unit-scoped Unverändert gegenüber WP2-001: - RuntimeContext - tenantbezogene Adapter - ReconciliationApplicationService --- # 7. Objektgraph ```text public/reconcile.php │ ▼ ReconciliationCompositionRoot │ ├────────► Configuration │ ├────────► DatabaseConnectionFactory │ ├────────► PDO │ ├────────► TransactionManager │ └────────► RuntimeFactory │ ▼ ReconciliationApplicationService ``` --- # 8. Datenbanksystem ## Zielsystem MySQL 8.x ## Entwicklungsumgebung MariaDB 10.4.x Die SQL-Skripte werden soweit möglich kompatibel zu beiden Systemen entwickelt. MySQL 8 bildet die Referenzplattform. --- # 9. Konfigurationsmodell Die Datenbankparameter werden Bestandteil der bestehenden Configuration. Typische Parameter sind - Host - Port - Datenbank - Benutzer - Passwort - Zeichensatz Die konkrete interne Struktur wird während der Implementierung festgelegt. --- # 10. Dependency Direction Die bestehende Dependency Direction bleibt unverändert. ```text Application │ ▼ Infrastructure Contracts │ ▼ Infrastructure Implementation ``` Die Application Layer kennt ausschließlich den Infrastructure Contract ``` TransactionManager ``` PDO bleibt vollständig innerhalb der Infrastructure Layer gekapselt. --- # 11. Architekturprinzipien Die Persistence Foundation folgt den bestehenden Architekturprinzipien von Reconcilix: - Constructor Injection - keine statischen Services - keine globalen Zustände - keine Service-Locator-Struktur - klare Trennung zwischen Application und Infrastructure - eindeutige Objektlebensdauern --- # 12. Nicht Bestandteil dieses Workpackages WP2-003 implementiert ausdrücklich nicht: - SQL-Schema - Migrationen - relationale Repositorys - Data Mapper - Rehydration - Persistierung fachlicher Aggregate - Unit of Work - Identity Map - SQL-Optimierungen Diese Themen werden in den nachfolgenden Workpackages umgesetzt. --- # 13. Teststrategie WP2-003 ergänzt Infrastrukturtests für - Aufbau der Datenbankverbindung - Erzeugung des TransactionManager - Integration in den Composition Root Zusätzlich wird überprüft: - keine doppelte Erzeugung der Verbindung innerhalb eines Objektgraphen - keine fachlichen Seiteneffekte beim Aufbau - keine Repository-Aufrufe - keine Reconciliation-Ausführung Der bestehende OpenRefine-End-to-End-Test bleibt unverändert Bestandteil der Integrationsprüfung. --- # 14. Auswirkungen Nach Abschluss von WP2-003 verfügt Reconcilix über eine vollständige technische Datenbankinfrastruktur. Die eigentliche relationale Persistierung erfolgt weiterhin erst in den folgenden Workpackages. Damit bildet WP2-003 die technische Grundlage für - WP2-004 – Schema and Migrations - WP2-005 – Relational Repositories and Data Mapper - WP2-006 – Rehydration - WP2-007 – Transactional Integration --- # Review-Ergebnis Das Architekturreview durch LA ergab: **Accepted with minor clarifications** Die Hinweise führten ausschließlich zu Präzisierungen hinsichtlich - der Transaction Boundary, - der Lebensdauer der Datenbankverbindung, - der expliziten Abgrenzung des Workpackage-Umfangs. Die zugrunde liegende Architekturentscheidung blieb unverändert. --- # Status **Accepted** WP2-003 kann implementiert werden.