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 |