# AM001 — Reconcilix Architecture Migration Plan **Version:** 1.0 **Status:** Final (Track A) **Scope:** Migration der bestehenden Reconcilix-Anwendung auf die Referenzarchitektur **Related:** DM001, DM002, ME001, ME002, ROADMAP_MATCHING --- # 1. Purpose Dieses Dokument beschreibt die schrittweise Migration der bestehenden Reconcilix-Anwendung auf die in den Referenzdokumenten definierte Architektur. Ziel der Migration ist nicht die Entwicklung einer neuen Anwendung, sondern die evolutionäre Überführung der bestehenden Codebasis in eine klar strukturierte, fachlich konsistente und langfristig erweiterbare Architektur. Die Migration erfolgt iterativ und bewahrt die vorhandene Funktionalität soweit wie möglich. --- # 2. Migration Scope ## Bestandteil der Migration - Integration des Domain Models (DM001) - Integration des Persistence Models (DM002) - Integration der Methodik (ME001, ME002) - Einführung einer persistenten Speicherung - Beibehaltung der OpenRefine-Kompatibilität - Vorbereitung zukünftiger Erweiterungen gemäß ROADMAP_MATCHING ## Nicht Bestandteil - vollständiger Rewrite - Performanceoptimierung - Event Sourcing - Graphdatenbank - KI-gestützte Candidate Discovery - weitere Entity Types Diese Themen werden in späteren Roadmap-Phasen behandelt. --- # 3. Current System Die bestehende Reconcilix-Anwendung besitzt bereits wesentliche funktionale Komponenten für die Reconciliation, basiert jedoch noch nicht auf dem neuen Domain Model. Aktueller Stand: - Übergabe des `SourceValue` aus OpenRefine - keine persistente Speicherung fachlicher Objekte - keine explizite Modellierung von InterpretationGraphs - keine expliziten InterpretationProperties - keine VocabularyMatchingPatterns - keine MatchDecision - keine ContextItem-Verwaltung Die Migration ersetzt diese Strukturen schrittweise durch die Referenzarchitektur. --- # 4. Target Architecture Die Zielarchitektur wird vollständig durch die Referenzdokumente beschrieben. | Dokument | Verantwortung | |----------|---------------| | DM001 | Domain Model | | DM002 | Persistence Model | | ME001 | Controlled Classifications | | ME002 | Interpretation-driven Reconciliation | | ROADMAP_MATCHING | Architectural Evolution | AM001 ergänzt diese Dokumente nicht, sondern beschreibt ausschließlich deren schrittweise Einführung. --- # 5. Migration Principles Die Migration folgt den folgenden Grundprinzipien. ## Evolution statt Rewrite Die bestehende Anwendung wird schrittweise erweitert. Bestehende Funktionalität wird möglichst erhalten. --- ## Architektur vor Implementierung Technische Entscheidungen orientieren sich an den Referenzdokumenten. Nicht umgekehrt. --- ## Kleine überprüfbare Schritte Jeder Migrationsschritt soll - implementierbar, - testbar, - evaluierbar sein. --- ## Persist first Die Einführung des Domain Models erfolgt gemeinsam mit der Persistenz. --- ## Refactoring vor Optimierung Optimierungen erfolgen erst nach erfolgreicher fachlicher Integration. --- ## Entkopplung Reconcilix bleibt unabhängig von - OpenRefine - xTree - lobid-gnd - externen Vector-Search-APIs - Embedding-Modellen Diese Systeme werden ausschließlich über definierte Schnittstellen integriert. --- # 6. Migration Work Packages ## WP1 — Domain Integration Einführung aller Domain Objects gemäß DM001. - SourceValue - ContextItem - InterpretationGraph - InterpretationNode - ReconciliationResult - CandidateItem - MatchDecision --- ## WP2 — Persistence Integration Einführung der relationalen Persistenz gemäß DM002. - MySQL - Repository Layer - Foreign Keys - Persistenz sämtlicher Domain Objects --- ## WP3 — Methodology Integration Integration der fachlichen Methodik. - InterpretationProperty - VocabularyMatchingPattern - Matching Strategy Selection - Interpretation Loop --- ## WP4 — OpenRefine Integration Beibehaltung der bestehenden OpenRefine-Kompatibilität. Erste Phase: - Übergabe des `SourceValue` Kontextinformationen werden über einen separaten Architecture Decision Record (ADR) vorbereitet und anschließend schrittweise integriert. --- ## WP5 — Evaluation Evaluation anhand realer Expertendaten. Insbesondere: - InterpretationProperty - VocabularyMatchingPattern - Candidate Discovery - Matching Strategies --- ## WP6 — Preparation for External Services Vorbereitung späterer Erweiterungen. Keine Implementierung. Insbesondere: - externes Vector-Search-API - lobid-gnd - weitere Target Vocabularies --- # 7. Architecture Risks Während der Migration sind insbesondere folgende Risiken zu beachten. ## Architecture Drift Implementierungen dürfen nicht schrittweise vom Domain Model abweichen. --- ## Vermischung von Domain und Technik Technische Frameworks dürfen keine fachlichen Modelle bestimmen. --- ## Vorzeitige Optimierung Performanceoptimierungen dürfen die Architektur nicht verändern. --- ## Enge Kopplung Reconcilix bleibt unabhängig von konkreten externen Diensten. --- ## Erweiterung ohne Evaluation Neue Matching Patterns oder Interpretation Properties werden ausschließlich anhand realer Expertendaten eingeführt. --- # 8. Required Architecture Decision Records Die folgenden ADRs werden für die weitere Entwicklung erwartet. | ADR | Thema | |------|------| | ADR001 | Repository Pattern | | ADR002 | Context Transfer Architecture | | ADR003 | External Vector Search API | | ADR004 | URI Strategy | | ADR005 | Candidate Discovery Integration | | ADR006 | External Vocabulary Connectors | Weitere ADRs entstehen während der Implementierung. --- # 9. Acceptance Criteria Die Architekturmigration gilt als erfolgreich abgeschlossen, wenn - DM001 vollständig umgesetzt ist, - DM002 vollständig umgesetzt ist, - ME001 vollständig integriert ist, - ME002 vollständig integriert ist, - sämtliche Domain Objects persistent gespeichert werden, - die bestehende OpenRefine-Kompatibilität erhalten bleibt, - erste Expertenevaluationen durchgeführt wurden, - keine Architekturentscheidung den Referenzdokumenten widerspricht. --- # 10. Handover to Engineering Mit Abschluss von AM001 endet der Architektur-Track (Track A). Die Referenzarchitektur von Reconcilix besteht nun aus: - DM001 — Domain Model - DM002 — Persistence Model - ME001 — Interpretation Properties and Vocabulary Matching Patterns - ME002 — Interpretation-driven Reconciliation - ROADMAP_MATCHING — Architectural Evolution - AM001 — Architecture Migration Plan Die Verantwortung für die Implementierung geht an den Engineering-Track (ED) über. Neue technische Entscheidungen erfolgen über Architecture Decision Records (ADR) und werden regelmäßig gegen die Referenzarchitektur überprüft. --- # 11. Closing Statement Die Migration verfolgt das Ziel, Reconcilix von einer prototypischen Reconciliation-Anwendung zu einer langfristig wartbaren, erweiterbaren und fachlich fundierten Interpretations- und Reconciliation-Plattform weiterzuentwickeln. Die Referenzarchitektur trennt bewusst Domain Model, Methodik, Persistenz und Engineering. Dadurch können zukünftige Erweiterungen – beispielsweise zusätzliche Entity Types, weitere Target Vocabularies oder neue Matching Techniques – integriert werden, ohne die fachlichen Grundlagen des Systems zu verändern.