Comprehensive FHIR Facade for OpenELIS Global.
Facade vs External Server
I am ISABIRYE ELIJAH ,as my Google Summer of Code journey finalize , I’m excited to share my final talk on the OpenELIS Global FHIR Facade and the architectural principles that enable interoperability between healthcare information systems.
This presentation explores more than the implementation of FHIR endpoints. It examines how the facade connects standards-based healthcare communication with OpenELIS application services, persistence, and data transformation — and why architectural choices matter when integrating systems such as OpenMRS and OpenELIS.
Part I — Understanding the Architecture
I’ll begin by tracing a FHIR request through the application, from the client-facing endpoint to the underlying database and back to a standards-compliant response.
Topics include:
- Core technologies: HAPI FHIR, HL7 FHIR R4, Spring Framework, Jakarta Persistence (JPA), and Hibernate.
- FHIR server configuration: Resource-provider discovery, registration, and request routing.
- Provider facades: How FHIR operations connect to OpenELIS application services.
- Search request processing: How HAPI FHIR parses search parameters and providers translate them into resource-specific search criteria.
- Persistence and query construction: How the JPA Criteria API uses
CriteriaBuilder,Predicate,Root,Expression, andSubquery, with Hibernate implementing the persistence operations. - Services, DAOs, and transactions: How search criteria become database queries against OpenELIS entities.
- Resource transformation and pagination: How application entities become FHIR R4 resources and paginated FHIR Bundles.
- CRUD operations: The implementation of read, create, update, and delete workflows, including validation and response handling.
- Shared utilities and error handling: How common provider utilities support consistent API behavior and synchronization where applicable.
Part II — Six Architectural Challenges and How the Facade Helps Address Them
6 Fact Issues resolved with the facade.
A key part of the talk will examine why an additional external FHIR server may introduce unnecessary overhead when the integration only requires a direct FHIR interface to OpenELIS.
1. Architectural complexity
An external server introduces another component, configuration surface, and integration boundary.
How the facade helps: It provides a FHIR interface within the OpenELIS integration architecture, reducing the number of components that must be configured and maintained.
2. Network latency
An additional server hop can increase request latency and create another processing step.
How the facade helps: Direct communication with the OpenELIS facade removes that additional hop, potentially improving response times.
3. Security and patient-data privacy
Every additional system that handles patient information introduces another security boundary, credential-management requirement, and potential exposure point.
How the facade helps: A direct integration can reduce the number of systems involved in the request path and simplify security management, provided authentication, authorization, encryption, and auditing are properly implemented.
4. Additional points of failure
An external FHIR server can become a dependency whose failure interrupts communication even when OpenMRS and OpenELIS remain operational.
How the facade helps: Removing that intermediary eliminates its availability as a separate dependency in the integration path. The facade and underlying services still require appropriate availability and resilience measures.
5. Data synchronization and consistency
A separate server that stores copies or cached representations of resources may require synchronization, conflict resolution, and recovery mechanisms.
How the facade helps: When the facade retrieves information through OpenELIS services rather than maintaining a separate copy, it can reduce synchronization overhead and the risk of stale data.
6. Configuration and maintenance overhead
Additional infrastructure means more deployments, upgrades, mappings, credentials, monitoring, and compatibility concerns.
How the facade helps: A direct facade-based architecture can consolidate the integration boundary and reduce the operational burden of managing a separate FHIR server.
Part III — Following a Search Request End to End
Search Architecture.
To connect the concepts to the implementation, I’ll trace a request such as:
GET /Practitoner?name=john&_count=20
The walk-through follows this path:
FHIR Client → HAPI FHIR Server → PractitionerProvider → PractitionerSearchService → PractitionerSearchDao → JPA Criteria API / Hibernate → OpenELIS Provider → FHIR Resource Transformation to Fhir Practitioner → FHIR Bundle
This demonstrates how protocol-level parameters are translated into application-level search criteria, database queries, and structured FHIR responses.
The central lesson
The value of a FHIR facade is not simply that it exposes REST endpoints. It is that it creates a clear boundary between healthcare interoperability standards and the application’s existing business logic and persistence mechanisms.
By connecting HAPI FHIR, Spring services, Jakarta Persistence, Hibernate, and resource-transformation components, the facade can provide a standards-based interface while preserving OpenELIS’s established application workflows.
The six challenges also illustrate an important engineering principle: the best architecture is not necessarily the one with the most components, but the one that provides the required capabilities with appropriate complexity, security, reliability, and maintainability.
I’m looking forward to sharing the implementation, architectural trade-offs, and lessons learned throughout my Google Summer of Code journey.
My sincere thanks to my mentors, the OpenELIS Global community, and everyone who contributed feedback and guidance throughout this experience. Open-source development is a collective effort, and this journey has been an invaluable opportunity to grow as a software engineer and contribute to healthcare interoperability.
Thank you, Google Summer of Code, and thank you to the OpenELIS Global community.
See this post on medium Comprehensive Fhir Facade for OpenELIS
gsoc
Mentor by Mr Mutesasira Moses aka @Moses_Mutesasira