ADR 018: Decide vor Modelling Component and Interfaces
Date: 2025-11-05
Status: Reviewed
Decision Makers: @luckey, @DerLinne
Context
This ADRArchitecture Decision RecordA document capturing an architecture decision. Each ADR has a stable identifier and short title and is managed through four lifecycle states: Proposed, Accepted, Deprecated and Superseded. 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 (UMLUnified Modeling LanguageA standardized notation used to represent and define Data structures in a visual way. In the Platform, it is used to describe the structure of data./XMI, XSDXML Schema DefinitionA W3C language for describing the structure of XML documents. Model Management imports XSD into JSON Schema and can serialize an Element as 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/XSDXML Schema DefinitionA W3C language for describing the structure of XML documents. Model Management imports XSD into JSON Schema and can serialize an Element as XSD., KafkaApache KafkaA distributed event streaming platform. In CIVITAS/CORE it is used as the message bus to transport events, models and data in data flows.-based)
- Model creation: Portal Frontend (UMLUnified Modeling LanguageA standardized notation used to represent and define Data structures in a visual way. In the Platform, it is used to describe the structure of data.) editor (UMLUnified Modeling LanguageA standardized notation used to represent and define Data structures in a visual way. In the Platform, it is used to describe the structure of data. 2.5.1 XMI interface, including a simplified tabular editor)
- Portal Backend: Custom-developed backend exposing UMLUnified Modeling LanguageA standardized notation used to represent and define Data structures in a visual way. In the Platform, it is used to describe the structure of data./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 (KafkaApache KafkaA distributed event streaming platform. In CIVITAS/CORE it is used as the message bus to transport events, models and data in data flows. integration)
- Integrate with the portal backend service using standard XMI UMLUnified Modeling LanguageA standardized notation used to represent and define Data structures in a visual way. In the Platform, it is used to describe the structure of data. 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 UMLUnified Modeling LanguageA standardized notation used to represent and define Data structures in a visual way. In the Platform, it is used to describe the structure of data. 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 KafkaApache KafkaA distributed event streaming platform. In CIVITAS/CORE it is used as the message bus to transport events, models and data in data flows. 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 UMLUnified Modeling LanguageA standardized notation used to represent and define Data structures in a visual way. In the Platform, it is used to describe the structure of data., XSDXML Schema DefinitionA W3C language for describing the structure of XML documents. Model Management imports XSD into JSON Schema and can serialize an Element as XSD., and JSON Schema
- Mult 4: Standards compliance - adherence to OMG UMLUnified Modeling LanguageA standardized notation used to represent and define Data structures in a visual way. In the Platform, it is used to describe the structure of data. 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 KafkaApache KafkaA distributed event streaming platform. In CIVITAS/CORE it is used as the message bus to transport events, models and data in data flows.
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 XSDXML Schema DefinitionA W3C language for describing the structure of XML documents. Model Management imports XSD into JSON Schema and can serialize an Element as 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/XSDXML Schema DefinitionA W3C language for describing the structure of XML documents. Model Management imports XSD into JSON Schema and can serialize an Element as 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 KafkaApache KafkaA distributed event streaming platform. In CIVITAS/CORE it is used as the message bus to transport events, models and data in data flows. 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
- KafkaApache KafkaA distributed event streaming platform. In CIVITAS/CORE it is used as the message bus to transport events, models and data in data flows. 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 (UMLUnified Modeling LanguageA standardized notation used to represent and define Data structures in a visual way. In the Platform, it is used to describe the structure of data., XSDXML Schema DefinitionA W3C language for describing the structure of XML documents. Model Management imports XSD into JSON Schema and can serialize an Element as 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/UMLUnified Modeling LanguageA standardized notation used to represent and define Data structures in a visual way. In the Platform, it is used to describe the structure of data./XMI standards | 16 | Medium - XSDXML Schema DefinitionA W3C language for describing the structure of XML documents. Model Management imports XSD into JSON Schema and can serialize an Element as 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/KafkaApache KafkaA distributed event streaming platform. In CIVITAS/CORE it is used as the message bus to transport events, models and data in data flows. | 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 UMLUnified Modeling LanguageA standardized notation used to represent and define Data structures in a visual way. In the Platform, it is used to describe the structure of data. 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.
- KafkaApache KafkaA distributed event streaming platform. In CIVITAS/CORE it is used as the message bus to transport events, models and data in data flows. 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 UMLUnified Modeling LanguageA standardized notation used to represent and define Data structures in a visual way. In the Platform, it is used to describe the structure of data. 2.5.1 for model creation and editing.
- Apicurio Registry: Used as persistent store (XML/XSDXML Schema DefinitionA W3C language for describing the structure of XML documents. Model Management imports XSD into JSON Schema and can serialize an Element as XSD./JSON Schema).
- KafkaApache KafkaA distributed event streaming platform. In CIVITAS/CORE it is used as the message bus to transport events, models and data in data flows. 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 |