Implement integration gateway base architecture

[jenniferjiangkells]

Description

Addresses #105 and #107 as part of the Integration layer milestone

New Features

• HealthChainAPI (gateway/api) - wraps FastAPI to provide healthcare-specific integrations, replaces the Service module.
• Gateways (gateway/protocols) - use cases in the previous sandbox module (cds and clindoc) are refactored as Gateway modules, which provide a consistent interface for handling different protocols through the decorator pattern for handler registration.
• EventDispatcher (gateway/events) - wraps fastapi-events and provides basic functionality for publishing events.
• Refactored sandbox to sandbox/ and deprecated @hc.api decorator as service is now handled by HealthChainAPI. The sandbox is only used to configure EHR clients now.
• Note FHIRGateway implements basic FHIR routes and client but is a work in progress.
• Removed support for Python 3.9 (dependencies req.)

Technical Implementation

• EventDispatcher is implemented as a mixin to BaseGateway
• Gateways implement Python Protocol typing and FastAPI dependency injection

Core Modules

• BaseGateway: The central abstraction for all protocol gateway implementations
• EventDispatcherMixin: A reusable mixin that provides event dispatching
• HealthChainAPI: FastAPI wrapper for healthcare gateway registration
• Concrete gateway implementations:
  • FHIRGateway: FHIR REST API protocol (WIP)
  • CDSHooksGateway: CDS Hooks protocol
  • NoteReaderGateway: SOAP/CDA protocol

Usage Examples

from healthchain.gateway import (
    HealthChainAPI, BaseGateway,
    FHIRGateway, CDSHooksGateway, NoteReaderGateway
)

# Create the application
app = HealthChainAPI()

# Create gateways for different protocols
cds = CDSHooksGateway()
soap = NoteReaderGateway()

@cds.hook("patient-view", id="allergy-check")
def handle_patient_view(request):
    return CDSResponse(cards=[...])

@soap.method("ProcessDocument")
def process_document(request):
    return CdaResponse(document=...)

# Register gateways with the application
app.register_gateway(cds)
app.register_gateway(soap)

uvicorn.run(app)

Updated sandbox usage:

# Create a sandbox for the Notereader gateway
@hc.sandbox("http://localhost:8000/") # api to test
class NotereaderSandbox(ClinicalDocumentation):
    def __init__(self):
        super().__init__()
        self.data_path = "./resources/uclh_cda.xml"

    # Register an EHR for the Notereader gateway
    @hc.ehr(workflow="sign-note-inpatient")
    def load_data_in_client(self) -> DocumentReference:
        with open(self.data_path, "r") as file:
            xml_string = file.read()

        cda_document_reference = create_document_reference(
            data=xml_string,
            content_type="text/xml",
            description="Original CDA Document loaded from my sandbox",
        )

        return cda_document_reference

Breaking Changes

• @hc.api is deprecated in sandbox
• @hc.sadbox decorator must take in api url argument

Documentation TODOs (for release)

• Update README.md sandbox usage
• Add HealthChainAPI section to README.md
• Update sandbox API documentation
• Add Gateway API documentation
• Add new examples to cookbook if time

[adamkells]

Looks good to me. I left a few comments, mostly to gain some clarifications for my own understanding. But overall it looks really good.