# ADR001-WP2-003 – Persistence Foundation **Status:** Proposed **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 jedoch keine direkte Abhängigkeit zu PDO oder konkreten Datenbankverbindungen besitzen. Ebenso soll die Datenbankkonfiguration zentral verwaltet werden. Die technische Datenbankinfrastruktur soll unabhängig von der fachlichen Persistierungslogik aufgebaut werden. --- # 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 Infrastruktur - 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 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 Einmal pro HTTP-Request: - Configuration - DatabaseConnectionFactory - PDO - TransactionManager --- ## 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 jedoch 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 ``` TransactionManager ``` PDO bleibt vollständig innerhalb der Infrastruktur. --- # 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 - keine fachlichen Seiteneffekte - 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 --- # 15. Offene Punkte für das LA-Review 1. Ist die Trennung zwischen DatabaseConnectionFactory und TransactionManager ausreichend klar? 2. Ist die Lebensdauer der PDO-Verbindung (application-scoped) sinnvoll gewählt? 3. Ist die Integration in den bestehenden Composition Root ausreichend klar beschrieben? 4. Ist die Abgrenzung zu WP2-004 eindeutig? 5. Fehlen infrastrukturelle Verantwortlichkeiten, die bereits Bestandteil der Persistence Foundation sein sollten? --- # Review Status **Proposed** Nach erfolgreichem Architekturreview durch LA kann WP2-003 implementiert werden.