InteropBridge

An HL7 v2.x to FHIR R4 clinical data integration gateway demonstrating end-to-end interoperability engineering.

What Is This?

InteropBridge is an enterprise-grade clinical data integration platform designed to bridge the gap between legacy healthcare systems (HL7 v2) and modern, API-first applications (FHIR R4). It acts as a robust message broker, parsing raw HL7 payloads, persisting them into a relational schema, and exposing the data securely via a SMART-on-FHIR compliant REST API. Finally, it features an ultra-premium "liquid glass" React dashboard to visualize the data pipeline in real-time.

Architecture

• Ingestion: Listens for incoming HL7 v2 messages (e.g., ADT, ORU) over MLLP.
• Processing: Parses and maps HL7 segments into a normalized PostgreSQL schema.
• API Layer: Exposes the data via a FastAPI-powered FHIR R4 endpoint.
• Authentication: Secured by Keycloak (OAuth2.0 / OpenID Connect) utilizing SMART-on-FHIR scopes.
• Frontend: A sleek React (Vite) dashboard built with TailwindCSS, featuring real-time data feeds, patient census grids, and full CRUD capabilities.

Technology Stack

• Backend: Python 3.11, FastAPI, asyncpg
• Integration Engine: Mirth Connect
• Database: PostgreSQL
• Identity Provider: Keycloak
• Frontend: React 18, Vite, TailwindCSS, TanStack Query, Framer Motion
• DevOps: Docker Compose

Quick Start

1. Clone the repository:

   git clone <repo-url>
   cd InteropBridge

2. Start the infrastructure:

   docker compose up -d --build

3. Start the Dashboard:

   cd dashboard
   npm install
   npm run dev

4. Generate Synthetic HL7 Data:

   docker compose exec fhir-api python /app/tools/simulate_hl7.py

5. Login to Dashboard: Navigate to http://localhost:3000 Credentials: dr.smith / password

Services

• React Dashboard: http://localhost:3000
• FHIR API: http://localhost:8080/fhir
• Keycloak IdP: http://localhost:8180 (Admin: admin / admin)
• Mirth Connect: https://localhost:8443 (Admin: admin / admin)
• PostgreSQL: localhost:5432

FHIR API Reference

The FastAPI backend supports standard FHIR operations:

• GET /fhir/Patient - Search patients
• GET /fhir/Patient/{id} - Retrieve a specific patient
• POST /fhir/Patient - Create a new patient
• PUT /fhir/Patient/{id} - Update a patient
• DELETE /fhir/Patient/{id} - Delete a patient and cascade dependent records
• GET /api/hl7-feed - Audit log for real-time MLLP ingestion visualization

SMART App Launch

The application implements the SMART-on-FHIR authorization paradigm. The frontend initiates an OAuth2 Authorization Code flow via Keycloak. It requests clinical scopes such as patient-wildcard-read and fhirUser.

Project Structure

• /mirth - Mirth Connect channels and deployment scripts
• /fhir_api - FastAPI application for the FHIR backend
• /dashboard - React frontend application
• /keycloak - Realm export and configuration for the IdP
• /tools - HL7 simulators and administrative scripts
• /db - Postgres initialization scripts

Testing & Automation

• Playwright E2E testing configured in dashboard/e2e for testing clinical workflows securely in mocked and live environments.
• Comprehensive Python testing available in /tests.