ADR 018: Decide vor Modelling Component and Interfaces

Date: 2025-11-05

Status: Reviewed

Decision Makers: @luckey, @DerLinne

Context

This ADR evaluates approaches for implementing the modeling component within the CIVITAS/CORE architecture. The modeling component is responsible for transforming, linking, and managing models originating from various domains and formats (UML/XMI, XSD, JSON Schema, etc.), and ensuring their persistence and discoverability within the model-centric data flow.

Related decisions:

• Model persistence: Apicurio Registry (OSS, supports XML/XSD, Kafka-based)
• Model creation: Portal Frontend (UML) editor (UML 2.5.1 XMI interface, including a simplified tabular editor)
• Portal Backend: Custom-developed backend exposing UML/XMI endpoints to Frontend and handling authorization/authentication. Passes through models to modelling component.

The modeling component must:

• Provide a unifying metamodel for model transformation and linking
• Persist and publish models through Apicurio (Kafka integration)
• Integrate with the portal backend service using standard XMI UML interface
• Enable referencing across heterogeneous model types

Applicable checked Architecture Principles

• [full] Model-centric data flow - Foundation of the model-driven architecture.
• [partial] Distributed architecture with unified user experience - Requires transparent integration of self-developed backend and modeling component.
• [full] Modular design - Clear separation of frontend, backend, and modeling logic.
• [full] Integration capability through defined interfaces - XMI UML 2.5.1 as standardized interface.
• [full] Open source as the default - EMF/Ecore and Apicurio are both open-source and will be.
• [partial] Cloud-native architecture - EMF is not inherently cloud-native but can be containerized.
• [partial] Prefer standard solutions over custom development - EMF/Ecore is standard, but additional custom transformations/codes are required.
• [partial] Self-contained deployment - Dependencies on Apicurio and Kafka remain (make sure to stabilized for resilience!)
• [full] Technological consistency to ensure maintainability - Built upon established OSS frameworks.
• [none] Multi-tenancy - To be handled at the application level or via multiple instance deployment.
• [partial] Security by design - Implemented mainly via backend services. Make sure in implementation!

Criteria

• Mult 5: Model interoperability - ability to transform and link across UML, XSD, and JSON Schema
• Mult 4: Standards compliance - adherence to OMG UML 2.5.1
• Mult 4: Maintainability - alignment with existing CIVITAS/CORE technology stack
• Mult 3: Performance - efficient transformation and persistence operations
• Mult 3: Integration capability - smooth interaction with Apicurio and Kafka

Evaluation Scale: 1: Low, 2: Medium, 3: High, 4: Very High Weight multiplier: 1–5 (importance)

Alternatives

A - EMF/Ecore-based custom modeling component

• Standardized metamodel (Ecore / EMOF)
• Rich transformation and reference management capabilities
• Open source and well-documented
• Direct support for XMI and extensible to XSD/JSON Schema
• Can be integrated with Apicurio for persistence (XML-based)
• Requires some custom glue logic and wrappers for REST APIs

B - Use Apicurio alone as the modeling repository

• Persisting models as XML/XSD/JSON Schema only
• No intrinsic understanding of model semantics or relationships
• No capability for model linking or transformation
• Simplifies persistence layer but loses semantic interoperability

C - Use a third-party modeling solution (e.g., Cameo, Enterprise Architect Server)

• Rich UI and tooling
• Proprietary, expensive, and not open source
• Poor integration with Kafka and Apicurio
• Limited extensibility for domain-specific metamodels

Negative Consequences

... of EMF/Ecore-based component

• Requires dedicated implementation and maintenance
• Limited native cloud support - must be containerized
• Multi-tenancy support needs to be handled externally
• Transformations must be explicitly developed for each supported format

... of Apicurio-only approach

• No model linking or cross-format referencing
• Limited transformation capabilities
• Purely structural persistence without semantic understanding

... of proprietary modeling servers

• Vendor lock-in and licensing costs
• Reduced architectural flexibility
• Difficult to integrate into existing CI/CD and infrastructure

Positive Benefits

... of EMF/Ecore-based component

• Unified metamodel layer: EMOF as an abstraction for heterogeneous model formats
• Transformation flexibility: Can link, transform, and reference across formats
• Full control: Internal data flow, transformation rules, and persistence behavior can be customized
• OSS ecosystem: Broad EMF community, active tooling, mature framework

... of Apicurio-only

• Simplified deployment and maintenance
• Kafka integration out-of-the-box
• Minimal operational complexity

... of proprietary modeling servers

• Powerful UIs and collaboration tools
• Mature lifecycle management features (versioning, review, publishing)

Comparison with Criteria

Criterium	EMF/Ecore Component	Eval	Apicurio-only	Eval	Proprietary Server	Eval
Model interoperability	Very high - transformations across formats (UML, XSD, JSON) possible	20	Low - no cross-format linking	5	Medium - limited extensibility beyond supported formats	9
Standards compliance	Very high - fully aligned with EMOF/UML/XMI standards	16	Medium - XSD/JSON only	8	Medium - vendor-specific extensions	8
Maintainability	High - OSS, large community, familiar stack (Java)	16	High - simple API layer	16	Low - proprietary stack, licensing	8
Performance	High - optimized model transformations and in-memory representation	9	High - lightweight registry	9	Medium - heavy server overhead	6
Integration capability	High - can serialize directly to Apicurio/Kafka	9	Very high - built-in integration	12	Low - requires adapters	6
		70		50		37

Decision

• We decide to implement the modeling component based on EMF/Ecore.
• For Model Persistence, apicurio will be used.
• Modelling will be done with a custom frontend development using the Standard UML XMI interface.

This approach provides the optimal balance between standard compliance, interoperability, and maintainability, while aligning with the CIVITAS/CORE architecture principles.

Key reasons:

• EMF/Ecore provides a unifying metamodel (EMOF) that allows cross-format model linking and referencing.
• Apicurio can be used as the persistence backend without additional data model fragmentation.
• Kafka integration ensures a model-centric event flow.
• OSS stack aligns with CIVITAS architectural principles.

Consequences

Impacted components:

• Modeling backend: Responsible for REST APIs, authentication, and authorization.
• Model editor frontend: Consumes XMI UML 2.5.1 for model creation and editing.
• Apicurio Registry: Used as persistent store (XML/XSD/JSON Schema).
• Kafka infrastructure: All model changes are published as events.

Positive effects:

• Unified model layer across the entire CIVITAS platform
• Standard-based interoperability and maintainability
• Seamless integration with existing OSS components

Challenges:

• Additional development effort for transformations and glue code
• Non-native cloud operation of EMF (requires containerization)
• Multi-tenancy must be implemented externally

Alternatives Summary

Alternative	Pros	Cons	Decision
EMF/Ecore Component	Standard-based, flexible, open source	Higher complexity, limited cloud-native	✅ Chosen
Apicurio-only	Simple, lightweight	No transformation or linking	❌ Rejected
Proprietary Server	Full-featured, mature UI	Vendor lock-in, not OSS	❌ Rejected