Add openEHR-to-FHIR R4 mapping library (fhir-facade module)

[devin-ai-integration]

Changes

• Add new fhir-facade Maven module providing a configuration-driven mapping layer between openEHR RM objects and FHIR R4 resources
• Mapping configuration (YAML-based):
  • MappingConfiguration, ResourceMapping, OpenEhrMappingConfig, FieldMapping classes for deserializing YAML mapping definitions
  • OpenEhrType enum (EHR_STATUS, COMPOSITION) for specifying the openEHR source type
  • Default mapping configs for Patient, Observation (blood pressure), and Condition (problem/diagnosis)
• Mapping service (OpenEhrFhirMappingService):
  • Read direction (openEHR → FHIR): mapToPatient(), mapToObservation(), mapToCondition()
  • Write direction (FHIR → openEHR): mapFromObservation(), mapFromCondition()
  • FHIR ID encoding/decoding: encodeFhirId() / decodeFhirId() using {ehrId}.{compositionId}.{version} format
  • YAML config loading from InputStream or directory Path
  • Archetype-aware reverse mapping: setJsonValueAtPath creates JSON arrays with archetype_node_id fields when path segments include bracket notation, preserving distinct sibling elements
• Dependencies: HAPI FHIR R4 7.6.0, Jackson YAML, EHRbase api module, Archie openEHR RM
• Module registration: Added fhir-facade to root pom.xml modules and BOM dependency management
• 17 unit tests covering:
  • Patient mapping (EhrStatus → Patient, inactive patient, null subject handling)
  • Observation mapping (Composition JSON → FHIR Observation with systolic/diastolic components, null handling, reverse mapping with archetype node ID preservation)
  • Condition mapping (Composition JSON → FHIR Condition, reverse mapping)
  • FHIR ID encoding/decoding round-trip and error handling
  • YAML configuration loading and field type distinction (constant vs. dynamic)

Related issue

N/A — New feature module for openEHR-to-FHIR interoperability.

Additional information

Design decisions:

• YAML-based mapping configuration allows adding new resource mappings without code changes
• Archetype path navigation uses Jackson JsonNode tree walking to extract values from serialized Composition JSON
• Reverse mapping (FHIR → openEHR) creates JSON arrays with archetype_node_id fields when path segments include archetype node IDs, preserving distinct sibling elements and enabling proper round-trip mapping
• Patient mapping is direct from EhrStatus (no archetype paths needed); Observation and Condition map from Composition using template-specific archetype paths

Build verification:

• mvn compile -pl fhir-facade -am -DskipTests — compiles successfully
• mvn test -pl fhir-facade — 17 tests pass
• mvn spotless:apply -pl fhir-facade — Palantir Java Format applied

Pre-Merge checklist

• New code is tested
• Present and new tests pass
• Documentation is updated
• The build is working without errors
• No new Sonar issues introduced
• Code has been reviewed
• Changelog is updated

Link to Devin session: https://app.devin.ai/sessions/7e2f093f3476479e97b568d432dc865b
Requested by: @Colhodm

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring