FHIR Facade Pattern

The Challenge of Legacy Systems

Healthcare organizations run on systems built decades ago. These legacy systems work, contain years of critical data, and staff know how to use them. But they weren't designed for modern interoperability. They speak HL7 v2 or proprietary protocols, not the RESTful APIs and JSON that today's applications expect.

Replacing legacy systems is expensive, risky, and disruptive. Migrations can take years and cost millions. During that time, clinical operations must continue. There's no pause button for patient care.

The FHIR Facade pattern offers an alternative: keep the legacy system running, but wrap it in a modern API layer. External applications see a clean FHIR interface. Behind the scenes, the facade translates between FHIR and whatever the legacy system speaks.

What is a Facade?

In software architecture, a facade is a simplified interface to a complex subsystem. Think of it as a helpful translator. One side speaks modern English (FHIR), the other speaks an obscure dialect (your legacy system's format). The facade handles translation so both sides can communicate.

The pattern originated in object-oriented programming but applies perfectly to healthcare integration. A FHIR Facade sits between external consumers and internal systems, exposing FHIR-compliant APIs while internally using whatever protocols the legacy systems require.

How FHIR Facade Works

Architecture Overview

The basic architecture has three layers:

1. API Layer (FHIR Interface): Accepts HTTP requests in FHIR format, validates them, and returns FHIR responses
2. Translation Layer (The Facade): Maps between FHIR resources and legacy data formats
3. Legacy System Layer: The existing database, application, or interface engine

When an application requests patient data via the FHIR API:

1. Request arrives: GET /Patient/12345
2. Facade validates the request and authenticates the caller
3. Facade queries the legacy system (maybe SQL, HL7 v2, or a proprietary API)
4. Legacy system returns data in its native format
5. Facade transforms the data into a FHIR Patient resource
6. FHIR response returns to the caller

The caller never knows it's not communicating directly with a modern FHIR server. From their perspective, it looks like any other FHIR API.

Translation Logic

The heart of a FHIR Facade is the translation logic. This is where you map legacy data elements to FHIR resources and vice versa. It's more nuanced than simple field mapping.

Challenges include:

• Data model mismatches: Legacy systems may store data differently than FHIR expects
• Missing data: FHIR requires certain elements that don't exist in the legacy system
• Extra data: Legacy systems may have fields with no FHIR equivalent
• Terminology differences: Codes and vocabularies may not align
• Cardinality differences: FHIR allows multiple values where legacy allows one, or vice versa

Good translation logic handles these gracefully, using default values, extensions, or omissions as appropriate.

{
  "name": [{
    "use": "official",
    "family": "Smith",
    "given": ["John", "Q"]
  }]
}

Benefits of the FHIR Facade Approach

1. Incremental Modernization

You don't have to replace everything at once. Start by exposing one resource (Patient), get it working, then add Observation, Medication, etc. Each step delivers value without a massive upfront investment.

2. Reduced Risk

The legacy system continues running as-is. You're not migrating data or changing clinical workflows. If the facade has issues, the core system is unaffected. Turn off the facade and you're back to the original state.

3. Faster Time-to-Value

Building a facade takes weeks or months, not years. Compare that to a full system replacement, which can take 2-5 years. You can deliver modern API access much sooner.

4. Interoperability Without Vendor Lock-in

Many legacy systems don't support FHIR or charge high prices for API access. A facade gives you control. You're not dependent on the vendor's roadmap or pricing.

5. Support for Modern Applications

Once you have a FHIR API, you can integrate with modern apps, patient portals, analytics platforms, and SMART on FHIR applications - none of which work with legacy protocols.

6. Future-Proofing

When you do eventually replace the legacy system, external integrations don't need to change. They still use the FHIR API. You just change what's behind the facade. This decouples integration from implementation.

Implementation Approaches

Custom Development

Build the facade using standard web frameworks (Node.js, Python, Java, .NET). You write the API endpoints and translation logic from scratch.

Pros:

• Complete control over functionality
• Can optimize for your specific use case
• No licensing costs for the facade itself

Cons:

• More development effort
• Need to handle FHIR validation, authentication, error handling yourself
• Ongoing maintenance burden

FHIR Server with Custom Plugins

Use an open-source FHIR server (like HAPI FHIR or Firely Server) and write custom providers or interceptors that retrieve data from your legacy system.

Pros:

• FHIR server handles validation, conformance, search parameters
• Focus on translation logic, not infrastructure
• Battle-tested FHIR implementation

Cons:

• Learning curve for the FHIR server platform
• May have performance overhead
• Some servers are better suited for storage than virtualization

Integration Platforms

Use an integration engine (like Mirth Connect, InterSystems HealthShare, or Rhapsody) configured to expose FHIR endpoints and translate to/from legacy formats.

Pros:

• Built-in connectors for common systems
• Visual mapping tools reduce coding
• Often already present in healthcare IT environments

Cons:

• Licensing costs can be high
• Complexity - integration platforms have steep learning curves
• May be overkill for simple use cases

Commercial FHIR Gateway Products

Some vendors sell FHIR gateway products designed specifically for this scenario. They come with pre-built translators for common legacy formats.

Pros:

• Fastest time to deployment
• Vendor support
• Pre-built mappings reduce development

Cons:

• Ongoing licensing costs
• Limited customization
• Another vendor dependency

Design Considerations

Read-Only vs Read-Write

Many facades start as read-only. External applications can query data but not modify it. This is simpler and lower risk - you're not worried about the facade corrupting legacy data.

Read-write facades are more powerful but complex. You must handle:

• Validation: Ensure incoming FHIR data is complete and correct
• Conflict detection: What if the data changed since the client read it?
• Error handling: What if the legacy system rejects the write?
• Audit trails: Who changed what, when?

Real-Time vs Cached

Real-time facades query the legacy system on every request. This guarantees freshness but can be slow if the legacy system has poor performance.

Cached facades periodically sync data from the legacy system into an intermediate store (like a FHIR server database). Queries hit the cache, not the legacy system. This improves performance but introduces latency - data might be minutes or hours old.

Hybrid approaches exist: cache stable data (patient demographics) but query real-time for frequently changing data (lab results).

Data Scope

You don't need to expose everything. Start with the FHIR resources most valuable to your use cases. Common starting points:

• Patient: Demographics, identifiers
• Observation: Lab results, vital signs
• Condition: Problem list, diagnoses
• MedicationRequest: Prescribed medications
• AllergyIntolerance: Known allergies

Expand scope as needs grow and you gain experience.

Security and Authentication

The facade must authenticate callers and authorize access. Options include:

• API keys: Simple but less secure for sensitive data
• OAuth 2.0: Industry standard, supports SMART on FHIR
• Mutual TLS: Certificate-based authentication for system-to-system
• SAML: Enterprise single sign-on integration

Access control is critical. Just because a system can authenticate doesn't mean it should see all data. Implement patient-level or role-based access controls.

Error Handling and Logging

Facades have two systems to worry about: the FHIR API and the legacy system. Errors can occur in either layer:

• Invalid FHIR requests (return HTTP 400 with OperationOutcome)
• Authentication failures (return HTTP 401/403)
• Data not found (return HTTP 404)
• Legacy system errors (return HTTP 500 with details)
• Translation failures (return HTTP 500 or 422)

Comprehensive logging is essential for troubleshooting. Log API requests, translation decisions, legacy system calls, and errors. But be careful with PHI in logs - sanitize or secure them.

Real-World Use Cases

Patient Portal Integration

A hospital wants to offer patients online access to their records via a modern patient portal. The EHR is a legacy system without FHIR support. Solution: Build a FHIR Facade that queries the EHR database, translates data to FHIR, and exposes it via a patient-facing API. The portal uses SMART on FHIR to authenticate patients and retrieve their data.

HIE Participation

A health information exchange (HIE) requires participants to provide FHIR APIs for data sharing. Small clinics with outdated systems can't meet this requirement. Solution: Deploy a community FHIR Facade that connects to multiple legacy systems, normalizes the data, and presents a unified FHIR interface to the HIE.

Analytics and Reporting

An analytics platform needs access to clinical data for population health reporting. Directly querying the legacy EHR database risks performance issues and requires deep knowledge of the schema. Solution: A FHIR Facade provides a stable, documented API. The analytics platform queries the facade using standard FHIR searches.

Third-Party App Integration

Clinicians want to use a specialized clinical decision support app. The app requires FHIR APIs, but the EHR doesn't provide them. Solution: Implement a FHIR Facade that supports SMART App Launch. The app integrates seamlessly as if the EHR natively supported FHIR.

Limitations and Trade-offs

Not a Complete Solution

A facade can't fix fundamental problems with legacy systems. If the underlying data quality is poor, the FHIR API will reflect that. If the legacy system is slow, the facade can't magically speed it up.

Maintenance Burden

Facades require ongoing maintenance. FHIR versions evolve. Legacy systems get patched or upgraded. Integration points break. You need resources to keep the facade running.

Data Fidelity

Translation inevitably loses nuance. Some legacy data may not map cleanly to FHIR. Using extensions helps but adds complexity.

Not Always Appropriate

If the legacy system is truly end-of-life or the data model is fundamentally incompatible with FHIR, a facade may not be worth the effort. Sometimes replacement is the right answer.

The Future of FHIR Facades

As interoperability mandates increase, FHIR Facades will become more common. They bridge the gap between regulatory requirements (modern APIs) and operational reality (legacy systems).

Emerging trends:

• AI-assisted mapping: Tools that analyze legacy data and suggest FHIR mappings
• Standardized translation libraries: Open-source projects providing common transformations
• Cloud-hosted facades: SaaS offerings that connect to on-premise legacy systems

Ultimately, facades are a transitional technology. As legacy systems are replaced, the need for facades diminishes. But that transition will take decades in healthcare. In the meantime, facades enable progress without waiting for perfection.