diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 6550ec38..b194cdec 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -8,9 +8,11 @@ on:
branches: [ "main" ]
pull_request:
branches: [ "main" ]
+ types: [opened, synchronize, reopened, ready_for_review]
jobs:
test:
+ if: github.event.pull_request.draft == false
strategy:
matrix:
python-version: ["3.9", "3.10", "3.11"]
diff --git a/.gitignore b/.gitignore
index aaa34162..ae3778db 100644
--- a/.gitignore
+++ b/.gitignore
@@ -165,3 +165,5 @@ scrap/
.vscode/
.ruff_cache/
.python-version
+.cursor/
+scripts/
diff --git a/README.md b/README.md
index 6ffc231b..9f9fed06 100644
--- a/README.md
+++ b/README.md
@@ -10,32 +10,115 @@
-Build simple, portable, and scalable AI and NLP applications in a healthcare context π« π₯.
+Connect your AI models to any healthcare system with a few lines of Python π« π₯.
+
+Integrating AI with electronic health records (EHRs) is complex, manual, and time-consuming. Let's try to change that.
-Integrating electronic health record systems (EHRs) data is complex, and so is designing reliable, reactive algorithms involving unstructured healthcare data. Let's try to change that.
```bash
pip install healthchain
```
First time here? Check out our [Docs](https://dotimplement.github.io/HealthChain/) page!
-Came here from NHS RPySOC 2024 β¨?
-[CDS sandbox walkthrough](https://dotimplement.github.io/HealthChain/cookbook/cds_sandbox/)
-[Slides](https://speakerdeck.com/jenniferjiangkells/building-healthcare-context-aware-applications-with-healthchain)
## Features
-- [x] π₯ Build FHIR-native pipelines or use [pre-built ones](https://dotimplement.github.io/HealthChain/reference/pipeline/pipeline/#prebuilt) for your healthcare NLP and ML tasks
-- [x] π Connect pipelines to any EHR system with built-in [CDA and FHIR Connectors](https://dotimplement.github.io/HealthChain/reference/pipeline/connectors/connectors/)
-- [x] π Convert between FHIR, CDA, and HL7v2 with the [InteropEngine](https://dotimplement.github.io/HealthChain/reference/interop/interop/)
-- [x] π§ͺ Test your pipelines in full healthcare-context aware [sandbox](https://dotimplement.github.io/HealthChain/reference/sandbox/sandbox/) environments
-- [x] ποΈ Generate [synthetic healthcare data](https://dotimplement.github.io/HealthChain/reference/utilities/data_generator/) for testing and development
-- [x] π Deploy sandbox servers locally with [FastAPI](https://fastapi.tiangolo.com/)
+- [x] π **Gateway**: Connect to multiple EHR systems with [unified API](https://dotimplement.github.io/HealthChain/reference/gateway/gateway/) supporting FHIR, CDS Hooks, and SOAP/CDA protocols
+- [x] π₯ **Pipelines**: Build FHIR-native ML workflows or use [pre-built ones](https://dotimplement.github.io/HealthChain/reference/pipeline/pipeline/#prebuilt) for your healthcare NLP and AI tasks
+- [x] π **InteropEngine**: Convert between FHIR, CDA, and HL7v2 with a [template-based engine](https://dotimplement.github.io/HealthChain/reference/interop/interop/)
+- [x] π Type-safe healthcare data with full type hints and Pydantic validation for [FHIR resources](https://dotimplement.github.io/HealthChain/reference/utilities/fhir_helpers/)
+- [x] β‘ Event-driven architecture with real-time event handling and [audit trails](https://dotimplement.github.io/HealthChain/reference/gateway/events/) built-in
+- [x] π Deploy production-ready applications with [HealthChainAPI](https://dotimplement.github.io/HealthChain/reference/gateway/api/) and FastAPI integration
+- [x] π§ͺ Generate [synthetic healthcare data](https://dotimplement.github.io/HealthChain/reference/utilities/data_generator/) and [sandbox testing](https://dotimplement.github.io/HealthChain/reference/sandbox/sandbox/) utilities
## Why use HealthChain?
-- **EHR integrations are manual and time-consuming** - HealthChain abstracts away complexities so you can focus on AI development, not EHR configurations.
-- **It's difficult to track and evaluate multiple integration instances** - HealthChain provides a framework to test the real-world resilience of your whole system, not just your models.
-- [**Most healthcare data is unstructured**](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6372467/) - HealthChain is optimized for real-time AI and NLP applications that deal with realistic healthcare data.
-- **Built by health tech developers, for health tech developers** - HealthChain is tech stack agnostic, modular, and easily extensible.
+- **EHR integrations are manual and time-consuming** - **HealthChainAPI** abstracts away complexities so you can focus on AI development, not learning FHIR APIs, CDS Hooks, and authentication schemes.
+- **Healthcare data is fragmented and complex** - **InteropEngine** handles the conversion between FHIR, CDA, and HL7v2 so you don't have to become an expert in healthcare data standards.
+- [**Most healthcare data is unstructured**](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6372467/) - HealthChain **Pipelines** are optimized for real-time AI and NLP applications that deal with realistic healthcare data.
+- **Built by health tech developers, for health tech developers** - HealthChain is tech stack agnostic, modular, and easily extensible with built-in compliance and audit features.
+
+## HealthChainAPI
+
+The HealthChainAPI provides a secure, asynchronous integration layer that coordinates multiple healthcare systems in a single application.
+
+### Multi-Protocol Support
+
+Connect to multiple healthcare data sources and protocols:
+
+```python
+from healthchain.gateway import (
+ HealthChainAPI, FHIRGateway,
+ CDSHooksService, NoteReaderService
+)
+
+# Create your healthcare application
+app = HealthChainAPI(
+ title="My Healthcare AI App",
+ description="AI-powered patient care platform"
+)
+
+# FHIR for patient data from multiple EHRs
+fhir = FHIRGateway()
+fhir.add_source("epic", "fhir://fhir.epic.com/r4?client_id=...")
+fhir.add_source("medplum", "fhir://api.medplum.com/fhir/R4/?client_id=...")
+
+# CDS Hooks for real-time clinical decision support
+cds = CDSHooksService()
+
+@cds.hook("patient-view", id="allergy-alerts")
+def check_allergies(request):
+ # Your AI logic here
+ return {"cards": [...]}
+
+# SOAP for clinical document processing
+notes = NoteReaderService()
+
+@notes.method("ProcessDocument")
+def process_note(request):
+ # Your NLP pipeline here
+ return processed_document
+
+# Register everything
+app.register_gateway(fhir)
+app.register_service(cds)
+app.register_service(notes)
+
+# Your API now handles:
+# /fhir/* - Patient data, observations, etc.
+# /cds/* - Real-time clinical alerts
+# /soap/* - Clinical document processing
+```
+
+### FHIR Operations with AI Enhancement
+
+```python
+from healthchain.gateway import FHIRGateway
+from fhir.resources.patient import Patient
+
+gateway = FHIRGateway()
+gateway.add_source("epic", "fhir://fhir.epic.com/r4?...")
+
+# Add AI transformations to FHIR data
+@gateway.transform(Patient)
+async def enhance_patient(id: str, source: str = None) -> Patient:
+ async with gateway.modify(Patient, id, source) as patient:
+ # Get lab results and process with AI
+ lab_results = await gateway.search(
+ Observation,
+ {"patient": id, "category": "laboratory"},
+ source
+ )
+ insights = nlp_pipeline.process(patient, lab_results)
+
+ # Add AI summary to patient record
+ patient.extension = patient.extension or []
+ patient.extension.append({
+ "url": "http://healthchain.org/fhir/summary",
+ "valueString": insights.summary
+ })
+ return patient
+
+# Automatically available at: GET /fhir/transform/Patient/123?source=epic
+```
## Pipeline
Pipelines provide a flexible way to build and manage processing pipelines for NLP and ML tasks that can easily integrate with complex healthcare systems.
@@ -139,116 +222,40 @@ cda_data = engine.from_fhir(fhir_resources, dest_format=FormatType.CDA)
## Sandbox
-Sandboxes provide a staging environment for testing and validating your pipeline in a realistic healthcare context.
-
-### Clinical Decision Support (CDS)
-[CDS Hooks](https://cds-hooks.org/) is an [HL7](https://cds-hooks.hl7.org) published specification for clinical decision support.
-
-**When is this used?** CDS hooks are triggered at certain events during a clinician's workflow in an electronic health record (EHR), e.g. when a patient record is opened, when an order is elected.
-
-**What information is sent**: the context of the event and [FHIR](https://hl7.org/fhir/) resources that are requested by your service, for example, the patient ID and information on the encounter and conditions they are being seen for.
-
-**What information is returned**: βcardsβ displaying text, actionable suggestions, or links to launch a [SMART](https://smarthealthit.org/) app from within the workflow.
-
+Test your AI applications in realistic healthcare contexts with [CDS Hooks](https://cds-hooks.org/) sandbox environments.
```python
import healthchain as hc
-
-from healthchain.pipeline import SummarizationPipeline
from healthchain.sandbox.use_cases import ClinicalDecisionSupport
-from healthchain.models import Card, Prefetch, CDSRequest
-from healthchain.data_generator import CdsDataGenerator
-from typing import List
@hc.sandbox
class MyCDS(ClinicalDecisionSupport):
- def __init__(self) -> None:
- self.pipeline = SummarizationPipeline.from_model_id(
- "facebook/bart-large-cnn", source="huggingface"
- )
- self.data_generator = CdsDataGenerator()
+ def __init__(self):
+ self.pipeline = SummarizationPipeline.from_model_id("facebook/bart-large-cnn")
- # Sets up an instance of a mock EHR client of the specified workflow
@hc.ehr(workflow="encounter-discharge")
- def ehr_database_client(self) -> Prefetch:
+ def ehr_database_client(self):
return self.data_generator.generate_prefetch()
- # Define your application logic here
- @hc.api
- def my_service(self, data: CDSRequest) -> CDSRequest:
- result = self.pipeline(data)
- return result
-```
-
-### Clinical Documentation
-
-The `ClinicalDocumentation` use case implements a real-time Clinical Documentation Improvement (CDI) service. It helps convert free-text medical documentation into coded information that can be used for billing, quality reporting, and clinical decision support.
-
-**When is this used?** Triggered when a clinician opts in to a CDI functionality (e.g. Epic NoteReader) and signs or pends a note after writing it.
-
-**What information is sent**: A [CDA (Clinical Document Architecture)](https://www.hl7.org.uk/standards/hl7-standards/cda-clinical-document-architecture/) document which contains continuity of care data and free-text data, e.g. a patient's problem list and the progress note that the clinician has entered in the EHR.
-
-```python
-import healthchain as hc
-
-from healthchain.pipeline import MedicalCodingPipeline
-from healthchain.sandbox.use_cases import ClinicalDocumentation
-from healthchain.models import CdaRequest, CdaResponse
-from fhir.resources.documentreference import DocumentReference
-
-@hc.sandbox
-class NotereaderSandbox(ClinicalDocumentation):
- def __init__(self):
- self.pipeline = MedicalCodingPipeline.from_model_id(
- "en_core_sci_md", source="spacy"
- )
-
- # Load an existing CDA file
- @hc.ehr(workflow="sign-note-inpatient")
- def load_data_in_client(self) -> DocumentReference:
- with open("/path/to/cda/data.xml", "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
-
- @hc.api
- def my_service(self, data: CdaRequest) -> CdaResponse:
- annotated_ccd = self.pipeline(data)
- return annotated_ccd
-```
-### Running a sandbox
-
-Ensure you run the following commands in your `mycds.py` file:
-
-```python
cds = MyCDS()
cds.start_sandbox()
-```
-This will populate your EHR client with the data generation method you have defined, send requests to your server for processing, and save the data in the `./output` directory.
-Then run:
-```bash
-healthchain run mycds.py
+# Run with: healthchain run mycds.py
```
-By default, the server runs at `http://127.0.0.1:8000`, and you can interact with the exposed endpoints at `/docs`.
## Road Map
-- [x] π Transform and validate healthcare HL7v2, CDA to FHIR with template-based interop engine
-- [ ] π₯ Runtime connection health and EHR integration management - connect to FHIR APIs and legacy systems
+- [ ] π Built-in HIPAA compliance validation and PHI detection
- [ ] π Track configurations, data provenance, and monitor model performance with MLFlow integration
- [ ] π Compliance monitoring, auditing at deployment as a sidecar service
-- [ ] π Built-in HIPAA compliance validation and PHI detection
-- [ ] π§ Multi-modal pipelines that that have built-in NLP to utilize unstructured data
+- [ ] π HL7v2 parsing and FHIR profile conversion support
+- [ ] π§ Multi-modal pipelines
+
## Contribute
We are always eager to hear feedback and suggestions, especially if you are a developer or researcher working with healthcare systems!
- π‘ Let's chat! [Discord](https://discord.gg/UQC6uAepUz)
- π οΈ [Contribution Guidelines](CONTRIBUTING.md)
-## Acknowledgement
-This repository makes use of [fhir.resources](https://github.com/nazrulworld/fhir.resources), and [CDS Hooks](https://cds-hooks.org/) developed by [HL7](https://www.hl7.org/) and [Boston Childrenβs Hospital](https://www.childrenshospital.org/).
+
+## Acknowledgements π€
+This project builds on [fhir.resources](https://github.com/nazrulworld/fhir.resources) and [CDS Hooks](https://cds-hooks.org/) standards developed by [HL7](https://www.hl7.org/) and [Boston Children's Hospital](https://www.childrenshospital.org/).
diff --git a/docs/assets/images/openapi_docs.png b/docs/assets/images/openapi_docs.png
new file mode 100644
index 00000000..76afa7cd
Binary files /dev/null and b/docs/assets/images/openapi_docs.png differ
diff --git a/docs/index.md b/docs/index.md
index 6d97fba0..53d9e534 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,6 +1,6 @@
-# Welcome to HealthChain
+# Welcome to HealthChain π« π₯
-HealthChain π«π₯ is an open-source Python framework designed to streamline the development, testing, and validation of AI, Natural Language Processing, and Machine Learning applications in a healthcare context.
+HealthChain is an open-source Python framework for building real-time AI applications in a healthcare context.
[ :fontawesome-brands-discord: Join our Discord](https://discord.gg/UQC6uAepUz){ .md-button .md-button--primary }
@@ -19,19 +19,19 @@ HealthChain π«π₯ is an open-source Python framework designed to streamline t
[:octicons-arrow-right-24: Pipeline](reference/pipeline/pipeline.md)
-- :octicons-beaker-24:{ .lg .middle } __Test in a sandbox__
+- :material-connection:{ .lg .middle } __Connect to multiple data sources__
---
- Test your models in a full health-context aware environment from day 1
+ Connect to multiple healthcare data sources and protocols with **HealthChainAPI**.
- [:octicons-arrow-right-24: Sandbox](reference/sandbox/sandbox.md)
+ [:octicons-arrow-right-24: Gateway](reference/gateway/gateway.md)
- :material-database:{ .lg .middle } __Interoperability__
---
- Configuration-driven InteropEngine to convert between FHIR, CDA, and HL7v2
+ Configuration-driven **InteropEngine** to convert between FHIR, CDA, and HL7v2
[:octicons-arrow-right-24: Interoperability](reference/interop/interop.md)
@@ -49,16 +49,17 @@ HealthChain π«π₯ is an open-source Python framework designed to streamline t
## Why HealthChain?
-You've probably heard every *AI will revolutionize healthcare* pitch by now, but if you're one of the people who think: wait, can we go beyond just vibe-checking and *actually* build products that are reliable, reactive, and easy to scale in complex healthcare systems? Then HealthChain is probably for you.
+Healthcare AI development has a **missing middleware layer**. Traditional enterprise integration engines move data around, EHR platforms serve end users, but there's nothing in between for developers building AI applications that need to talk to multiple healthcare systems. Few solutions are open-source, and even fewer are built in modern Python where most ML/AI libraries thrive.
-Specifically, HealthChain addresses two challenges:
+HealthChain fills that gap with:
-1. **Scaling Electronic Health Record system (EHRs) integrations of real-time AI, NLP, and ML applications is a manual and time-consuming process.**
+- **π₯ FHIR-native ML pipelines** - Pre-built NLP/ML pipelines optimized for structured / unstructured healthcare data, or build your own with familiar Python libraries such as π€ Hugging Face, π€ LangChain, and π spaCy
+- **π Type-safe healthcare data** - Full type hints and Pydantic validation for FHIR resources with automatic data validation and error handling
+- **π Multi-protocol connectivity** - Handle FHIR, CDS Hooks, and SOAP/CDA in the same codebase with OAuth2 authentication and connection pooling
+- **β‘ Event-driven architecture** - Real-time event handling with audit trails and workflow automation built-in
+- **π Built-in interoperability** - Convert between FHIR, CDA, and HL7v2 using a template-based engine
+- **π Production-ready deployment** - FastAPI integration for scalable, real-time applications
-2. **Testing and evaluating unstructured data in complex, outcome focused systems is a challenging and labour-intensive task.**
-
-We believe more efficient end-to-end pipeline and integration testing at an early stage in development will give you back time to focus on what actually matters: developing safer, more effective and more explainable models that scale to real-world *adoption*. Building products for healthcare in a process that is *human*-centric.
-
-HealthChain is made by a (very) small team with experience in software engineering, machine learning, and healthcare NLP. We understand that good data science is about more than just building models, and that good engineering is about more than just building systems. This rings especially true in healthcare, where people, processes, and technology all play a role in making an impact.
+HealthChain is made by a small team with experience in software engineering, machine learning, and healthcare NLP. We understand that good data science is about more than just building models, and that good engineering is about more than just building systems. This rings especially true in healthcare, where people, processes, and technology all play a role in making an impact.
For inquiries and collaborations, please get [in touch](mailto:jenniferjiangkells@gmail.com)!
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 816e621e..660ca885 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -2,8 +2,41 @@
After [installing HealthChain](installation.md), get up to speed quickly with the core components before diving further into the [full documentation](reference/index.md)!
+HealthChain provides three core tools for healthcare AI integration: **Gateway** for connecting to multiple healthcare systems, **Pipelines** for FHIR-native AI workflows, and **InteropEngine** for healthcare data format conversion between FHIR, CDA, and HL7v2.
+
## Core Components
+### HealthChainAPI Gateway π
+
+The HealthChainAPI provides a unified interface for connecting your AI models to multiple healthcare systems through a single API. Handle FHIR, CDS Hooks, and SOAP/CDA protocols with OAuth2 authentication and connection pooling.
+
+[(Full Documentation on Gateway)](./reference/gateway/gateway.md)
+
+```python
+from healthchain.gateway import HealthChainAPI, FHIRGateway
+
+# Create your healthcare application
+app = HealthChainAPI(title="My Healthcare AI App")
+
+# Connect to multiple FHIR servers
+fhir = FHIRGateway()
+fhir.add_source("epic", "fhir://fhir.epic.com/r4?client_id=...")
+fhir.add_source("medplum", "fhir://api.medplum.com/fhir/R4/?client_id=...")
+
+# Add AI transformations to FHIR data
+@fhir.transform(Patient)
+async def enhance_patient(id: str, source: str = None) -> Patient:
+ async with fhir.modify(Patient, id, source) as patient:
+ # Your AI logic here
+ patient.active = True
+ return patient
+
+# Register and run
+app.register_gateway(fhir)
+
+# Available at: GET /fhir/transform/Patient/123?source=epic
+```
+
### Pipeline π οΈ
HealthChain Pipelines provide a flexible way to build and manage processing pipelines for NLP and ML tasks that can easily integrate with electronic health record (EHR) systems.
@@ -149,72 +182,30 @@ The interop module provides a flexible, template-based approach to healthcare fo
For more details, see the [conversion examples](cookbook/interop/basic_conversion.md).
-### Sandbox π§ͺ
-Once you've built your pipeline, you might want to experiment with how it interacts with different healthcare systems. A sandbox helps you stage and test the end-to-end workflow of your pipeline application where real-time EHR integrations are involved.
-
-Running a sandbox will start a [FastAPI](https://fastapi.tiangolo.com/) server with pre-defined standardized endpoints and create a sandboxed environment for you to interact with your application.
+## Utilities βοΈ
-To create a sandbox, initialize a class that inherits from a type of [UseCase](./reference/sandbox/use_cases/use_cases.md) and decorate it with the `@hc.sandbox` decorator.
+### Sandbox Testing
-Every sandbox also requires a **client** function marked by `@hc.ehr` and a **service** function marked by `@hc.api`. A **workflow** must be specified when creating an EHR client.
+Test your AI applications in realistic healthcare contexts with sandbox environments for CDS Hooks and clinical documentation workflows.
-[(Full Documentation on Sandbox and Use Cases)](./reference/sandbox/sandbox.md)
+[(Full Documentation on Sandbox)](./reference/sandbox/sandbox.md)
```python
import healthchain as hc
-
-from healthchain.sandbox.use_cases import ClinicalDocumentation
-from healthchain.pipeline import MedicalCodingPipeline
-from healthchain.models import CdaRequest, CdaResponse
-from healthchain.fhir import create_document_reference
-
-from fhir.resources.documentreference import DocumentReference
+from healthchain.sandbox.use_cases import ClinicalDecisionSupport
@hc.sandbox
-class MyCoolSandbox(ClinicalDocumentation):
- def __init__(self) -> None:
- # Load your pipeline
- self.pipeline = MedicalCodingPipeline.from_local_model(
- "./path/to/model", source="spacy"
- )
-
- @hc.ehr(workflow="sign-note-inpatient")
- def load_data_in_client(self) -> DocumentReference:
- # Load your data
- with open('/path/to/data.xml', "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
-
- @hc.api
- def my_service(self, request: CdaRequest) -> CdaResponse:
- # Run your pipeline
- results = self.pipeline(request)
- return results
-
-if __name__ == "__main__":
- clindoc = MyCoolSandbox()
- clindoc.start_sandbox()
-```
-
-#### Deploy sandbox locally with FastAPI π
+class MyCDS(ClinicalDecisionSupport):
+ def __init__(self):
+ self.pipeline = SummarizationPipeline.from_model_id("facebook/bart-large-cnn")
-To run your sandbox:
+ @hc.ehr(workflow="encounter-discharge")
+ def ehr_database_client(self):
+ return self.data_generator.generate_prefetch()
-```bash
-healthchain run my_sandbox.py
+# Run with: healthchain run mycds.py
```
-This will start a server by default at `http://127.0.0.1:8000`, and you can interact with the exposed endpoints at `/docs`. Data generated from your sandbox runs is saved at `./output/` by default.
-
-## Utilities βοΈ
-
### FHIR Helpers
The `fhir` module provides a set of helper functions for working with FHIR resources.
diff --git a/docs/reference/gateway/api.md b/docs/reference/gateway/api.md
new file mode 100644
index 00000000..29a4b3eb
--- /dev/null
+++ b/docs/reference/gateway/api.md
@@ -0,0 +1,181 @@
+# HealthChainAPI π₯
+
+The `HealthChainAPI` is your main application that coordinates all the different gateways and services.
+
+It's a [FastAPI](https://fastapi.tiangolo.com/) app under the hood, so you get all the benefits of FastAPI (automatic docs, type safety, performance) plus healthcare-specific features that makes it easier to work with healthcare data sources, such as FHIR APIs, CDS Hooks, and SOAP/CDA services.
+
+
+## Basic Usage
+
+
+```python
+from healthchain.gateway import HealthChainAPI, FHIRGateway
+import uvicorn
+
+# Create your app
+app = HealthChainAPI(
+ title="My Healthcare App",
+ description="AI-powered patient care",
+)
+
+# Add a FHIR gateway
+fhir = FHIRGateway()
+app.register_gateway(fhir)
+
+# Run it (docs automatically available at /docs)
+if __name__ == "__main__":
+ uvicorn.run(app)
+```
+
+You can also register multiple services of different protocols:
+
+```python
+from healthchain.gateway import (
+ HealthChainAPI, FHIRGateway,
+ CDSHooksService, NoteReaderService
+)
+
+app = HealthChainAPI()
+
+# Register everything you need
+app.register_gateway(FHIRGateway(), path="/fhir")
+app.register_service(CDSHooksService(), path="/cds")
+app.register_service(NoteReaderService(), path="/soap")
+
+# Your API now handles:
+# /fhir/* - Patient data, observations, etc.
+# /cds/* - Real-time clinical alerts
+# /soap/* - Clinical document processing
+```
+
+## Default Endpoints
+
+
+
+The HealthChainAPI automatically provides several default endpoints:
+
+### Root Endpoint: `GET /`
+
+Returns basic API information and registered components.
+
+```json
+{
+ "name": "HealthChain API",
+ "version": "1.0.0",
+ "description": "Healthcare Integration Platform",
+ "gateways": ["FHIRGateway"],
+ "services": ["CDSHooksService", "NoteReaderService"]
+}
+```
+
+### Health Check: `GET /health`
+
+Simple health check endpoint for monitoring.
+
+```json
+{
+ "status": "healthy"
+}
+```
+
+### Gateway Status: `GET /gateway/status`
+
+Comprehensive status of all registered gateways and services.
+
+```json
+{
+ "gateways": {
+ "FHIRGateway": {
+ "status": "active",
+ "sources": ["epic", "cerner"],
+ "connection_pool": {...}
+ }
+ },
+ "services": {
+ "CDSHooksService": {
+ "status": "active",
+ "hooks": ["patient-view", "order-select"]
+ }
+ },
+ "events": {
+ "enabled": true,
+ "dispatcher": "LocalEventDispatcher"
+ }
+}
+```
+
+
+## Event Integration
+
+The HealthChainAPI coordinates events across all registered components. This is useful for auditing, workflow automation, and other use cases. For more information, see the **[Events](events.md)** page.
+
+
+```python
+from healthchain.gateway.events.dispatcher import local_handler
+
+app = HealthChainAPI()
+
+# Register global event handler
+@local_handler.register(event_name="fhir.patient.read")
+async def log_patient_access(event):
+ event_name, payload = event
+ print(f"Patient accessed: {payload['resource_id']}")
+
+# Register handler for all events from specific component
+@local_handler.register(event_name="cdshooks.*")
+async def log_cds_events(event):
+ event_name, payload = event
+ print(f"CDS Hook fired: {event_name}")
+```
+
+## Dependencies and Injection
+
+The HealthChainAPI provides dependency injection for accessing registered components.
+
+### Gateway Dependencies
+
+```python
+from healthchain.gateway.api.dependencies import get_gateway
+from fastapi import Depends
+
+@app.get("/custom/patient/{id}")
+async def get_enhanced_patient(
+ id: str,
+ fhir: FHIRGateway = Depends(get_gateway("FHIRGateway"))
+):
+ """Custom endpoint using FHIR gateway dependency."""
+ patient = await fhir.read(Patient, id)
+ return patient
+
+# Or get all gateways
+from healthchain.gateway.api.dependencies import get_all_gateways
+
+@app.get("/admin/gateways")
+async def list_gateways(
+ gateways: Dict[str, Any] = Depends(get_all_gateways)
+):
+ return {"gateways": list(gateways.keys())}
+```
+
+### Application Dependencies
+
+```python
+from healthchain.gateway.api.dependencies import get_app
+
+@app.get("/admin/status")
+async def admin_status(
+ app_instance: HealthChainAPI = Depends(get_app)
+):
+ return {
+ "gateways": len(app_instance.gateways),
+ "services": len(app_instance.services),
+ "events_enabled": app_instance.enable_events
+ }
+```
+
+
+## See Also
+
+- **[FHIR Gateway](fhir_gateway.md)**: Complete FHIR operations reference
+- **[CDS Hooks Service](cdshooks.md)**: Complete CDS Hooks service reference
+- **[NoteReader Service](soap_cda.md)**: Complete NoteReader service reference
diff --git a/docs/reference/gateway/cdshooks.md b/docs/reference/gateway/cdshooks.md
new file mode 100644
index 00000000..6564a4a4
--- /dev/null
+++ b/docs/reference/gateway/cdshooks.md
@@ -0,0 +1,105 @@
+# CDS Hooks Protocol
+
+CDS Hooks is an [HL7](https://cds-hooks.hl7.org) published specification for clinical decision support that enables external services to provide real-time recommendations during clinical workflows.
+
+## Overview
+
+CDS hooks are triggered at specific events during a clinician's workflow in an electronic health record (EHR), such as when a patient record is opened or when an order is selected. The hooks communicate using [FHIR (Fast Healthcare Interoperability Resources)](https://hl7.org/fhir/).
+
+CDS Hooks are unique in that they are *real-time* webhooks that are triggered by the EHR, not by external services. This makes them ideal for real-time clinical decision support and alerts, but also trickier to test and debug for a developer. They are also a relatively new standard, so not all EHRs support them yet.
+
+| When | Where | What you receive | What you send back | Common Use Cases |
+| :-------- | :-----| :-------------------------- |----------------------------|-----------------|
+| Triggered at certain events during a clinician's workflow | EHR | The context of the event and FHIR resources that are requested by your service | "Cards" displaying text, actionable suggestions, or links to launch a [SMART](https://smarthealthit.org/) app | Allergy alerts, medication reconciliation, clinical decision support |
+
+## HealthChainAPI Integration
+
+Use the `CDSHooksService` with HealthChainAPI to handle CDS Hooks workflows:
+
+```python
+from healthchain.gateway import HealthChainAPI, CDSHooksService
+from healthchain.models import CDSRequest, CDSResponse
+
+app = HealthChainAPI()
+cds = CDSHooksService()
+
+@cds.hook("patient-view", id="allergy-alerts")
+def check_allergies(request: CDSRequest) -> CDSResponse:
+ # Your AI logic here
+ return CDSResponse(cards=[...])
+
+app.register_service(cds, path="/cds")
+```
+
+## Supported Workflows
+
+| Workflow Name | Description | Trigger | Status |
+|-----------|-------------|---------|----------|
+| `patient-view` | Triggered when a patient chart is opened | Opening a patient's chart | β
|
+| `order-select` | Triggered when a new order is selected | Selecting a new order | β³ |
+| `order-sign` | Triggered when orders are being signed | Signing orders | β³ |
+| `encounter-discharge` | Triggered when a patient is being discharged | Discharging a patient | β
|
+
+## API Endpoints
+
+When registered with HealthChainAPI, the following endpoints are automatically created:
+
+| Endpoint | Method | Function | Description |
+|------|--------|----------|-------------|
+| `/cds-services` | GET | Service Discovery | Lists all available CDS services |
+| `/cds-services/{id}` | POST | Hook Execution | Executes the specified CDS hook |
+
+## Request/Response Format
+
+### CDSRequest Example
+
+```json
+{
+ "hookInstance": "23f1a303-991f-4118-86c5-11d99a39222e",
+ "fhirServer": "https://fhir.example.org",
+ "hook": "patient-view",
+ "context": {
+ "patientId": "1288992",
+ "userId": "Practitioner/example"
+ },
+ "prefetch": {
+ "patientToGreet": {
+ "resourceType": "Patient",
+ "gender": "male",
+ "birthDate": "1925-12-23",
+ "id": "1288992",
+ "active": true
+ }
+ }
+}
+```
+
+### CDSResponse Example
+
+```json
+{
+ "cards": [{
+ "summary": "Bilirubin: Based on the age of this patient consider overlaying bilirubin results",
+ "indicator": "info",
+ "detail": "The focus of this app is to reduce the incidence of severe hyperbilirubinemia...",
+ "source": {
+ "label": "Intermountain",
+ "url": null
+ },
+ "links": [{
+ "label": "Bilirubin SMART app",
+ "url": "https://example.com/launch",
+ "type": "smart"
+ }]
+ }]
+}
+```
+
+## Supported FHIR Resources
+
+- `Patient`
+- `Encounter`
+- `Procedure`
+- `MedicationRequest`
+
+For more information, see the [official CDS Hooks documentation](https://cds-hooks.org/).
diff --git a/docs/reference/gateway/events.md b/docs/reference/gateway/events.md
new file mode 100644
index 00000000..e850f9b9
--- /dev/null
+++ b/docs/reference/gateway/events.md
@@ -0,0 +1,76 @@
+# Events
+
+The FHIR Gateway emits events for all operations. The events are emitted using the `EventDispatcher`.
+
+!!! warning "Develoment Use Only"
+ This is a development feature and may change in future releases.
+
+
+
+## Event System
+
+The FHIR Gateway uses the `EventDispatcher` to emit events.
+
+## Event Types
+
+- `ehr.generic`
+- `fhir.read`
+- `fhir.search`
+- `fhir.update`
+- `fhir.delete`
+- `fhir.create`
+- `cds.patient.view`
+- `cds.encounter.discharge`
+- `cds.order.sign`
+- `cds.order.select`
+- `notereader.sign.note`
+- `notereader.process.note`
+
+## Automatic Events
+
+The FHIR Gateway automatically emits events for all operations:
+
+```python
+from healthchain.gateway.events.dispatcher import local_handler
+
+# Listen for FHIR read events
+@local_handler.register(event_name="fhir.read")
+async def audit_fhir_access(event):
+ event_name, payload = event
+ print(f"FHIR Read: {payload['resource_type']}/{payload['resource_id']} from {payload.get('source', 'unknown')}")
+
+# Listen for patient-specific events
+@local_handler.register(event_name="fhir.patient.*")
+async def track_patient_access(event):
+ event_name, payload = event
+ operation = event_name.split('.')[-1] # read, create, update, delete
+ print(f"Patient {operation}: {payload['resource_id']}")
+```
+
+### Custom Event Creation
+
+```python
+# Configure custom event creation
+def custom_event_creator(operation, resource_type, resource_id, resource=None, source=None):
+ """Create custom events with additional metadata."""
+ return EHREvent(
+ event_type=EHREventType.FHIR_READ,
+ source_system=source or "unknown",
+ timestamp=datetime.now(),
+ payload={
+ "operation": operation,
+ "resource_type": resource_type,
+ "resource_id": resource_id,
+ "user_id": get_current_user_id(), # Your auth system
+ "session_id": get_session_id(),
+ "ip_address": get_client_ip()
+ },
+ metadata={
+ "compliance": "HIPAA",
+ "audit_required": True
+ }
+ )
+
+# Apply to gateway
+gateway.events.set_event_creator(custom_event_creator)
+```
diff --git a/docs/reference/gateway/fhir_gateway.md b/docs/reference/gateway/fhir_gateway.md
new file mode 100644
index 00000000..007882b0
--- /dev/null
+++ b/docs/reference/gateway/fhir_gateway.md
@@ -0,0 +1,293 @@
+# FHIR Gateway
+
+The `FHIRGateway` provides a unified **asynchronous** interface for connecting to multiple FHIR servers with automatic authentication, connection pooling, error handling, and simplified CRUD operations. It handles the complexity of managing multiple FHIR clients and provides a consistent API across different healthcare systems.
+
+
+## Basic Usage
+
+```python
+from healthchain.gateway import FHIRGateway
+from fhir.resources.patient import Patient
+
+# Create gateway
+gateway = FHIRGateway()
+
+# Connect to FHIR server
+gateway.add_source(
+ "my_fhir_server",
+ "fhir://fhir.example.com/api/FHIR/R4/?client_id=your_app&client_secret=secret&token_url=https://fhir.example.com/oauth2/token"
+)
+
+async with gateway:
+ # FHIR operations
+ patient = await gateway.read(Patient, "123", "my_fhir_server")
+ print(f"Patient: {patient.name[0].family}")
+```
+
+
+## Adding Sources π₯
+
+The gateway currently supports adding sources with OAuth2 authentication flow.
+
+```python
+# Epic Sandbox (JWT assertion)
+gateway.add_source(
+ "epic",
+ (
+ "fhir://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4/"
+ "?client_id=your_app"
+ "&client_secret_path=keys/private.pem"
+ "&token_url=https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token"
+ "&use_jwt_assertion=true"
+ )
+)
+
+# Medplum (Client Credentials)
+gateway.add_source(
+ "medplum",
+ (
+ "fhir://api.medplum.com/fhir/R4/"
+ "?client_id=your_app"
+ "&client_secret=secret"
+ "&token_url=https://api.medplum.com/oauth2/token"
+ "&scope=openid"
+ )
+)
+```
+!!! info "For more information on configuring specific FHIR servers"
+
+ **Epic FHIR API:**
+
+ - [Epic on FHIR Documentation](https://fhir.epic.com/)
+ - [Epic OAuth2 Setup](https://fhir.epic.com/Documentation?docId=oauth2)
+ - [Test Patients in Epic Sandbox](https://fhir.epic.com/Documentation?docId=testpatients)
+ - [Useful Epic Sandbox Setup Guide](https://docs.interfaceware.com/docs/IguanaX_Documentation_Home/Development/iNTERFACEWARE_Collections/HL7_Collection/Epic_FHIR_Adapter/Set_up_your_Epic_FHIR_Sandbox_2783739933/)
+
+ **Medplum FHIR API:**
+
+ - [Medplum app tutorial](https://www.medplum.com/docs/tutorials)
+ - [Medplum OAuth2 Client Credentials Setup](https://www.medplum.com/docs/auth/methods/client-credentials)
+
+ **General Resources:**
+
+ - [OAuth2](https://oauth.net/2/)
+ - [FHIR RESTful API](https://hl7.org/fhir/http.html)
+ - [FHIR Specification](https://hl7.org/fhir/)
+
+
+### Connection String Format
+
+Connection strings use the `fhir://` scheme with query parameters:
+
+```
+fhir://hostname:port/path?param1=value1¶m2=value2
+```
+
+**Required Parameters:**
+
+- `client_id`: OAuth2 client ID
+- `token_url`: OAuth2 token endpoint
+
+**Optional Parameters:**
+
+- `client_secret`: OAuth2 client secret (for client credentials flow)
+- `client_secret_path`: Path to private key file (for JWT assertion)
+- `scope`: OAuth2 scope (default: "`system/*.read system/*.write`")
+- `use_jwt_assertion`: Use JWT assertion flow (default: false)
+- `audience`: Token audience (for some servers)
+
+
+## FHIR Operations π₯
+
+!!! note Prerequisites
+ These examples assume you have already created and configured your gateway as shown in the [Basic Usage](#basic-usage) section above.
+
+### Create Resources
+
+```python
+from fhir.resources.patient import Patient
+from fhir.resources.humanname import HumanName
+
+# Create a new patient
+patient = Patient(
+ name=[HumanName(family="Smith", given=["John"])],
+ gender="male",
+ birthDate="1990-01-01"
+)
+
+created_patient = await gateway.create(resource=patient, source="medplum")
+print(f"Created patient with ID: {created_patient.id}")
+```
+
+### Read Resources
+
+```python
+from fhir.resources.patient import Patient
+
+# Read a specific patient (Derrick Lin, Epic Sandbox)
+patient = await gateway.read(
+ resource_type=Patient,
+ fhir_id="eq081-VQEgP8drUUqCWzHfw3",
+ source="epic"
+ )
+```
+
+### Update Resources
+
+```python
+from fhir.resources.patient import Patient
+
+# Read, modify, and update
+patient = await gateway.read(Patient, "123", "medplum")
+patient.name[0].family = "Johnson"
+updated_patient = await gateway.update(patient, "medplum")
+
+# Using context manager
+async with gateway.modify(Patient, "123", "medplum") as patient:
+ patient.active = True
+ patient.name[0].given = ["Jane"]
+ # Automatic save on exit
+```
+
+### Delete Resources
+
+```python
+from fhir.resources.patient import Patient
+
+# Delete a patient
+success = await gateway.delete(Patient, "123", "medplum")
+if success:
+ print("Patient deleted successfully")
+```
+
+## Search Operations
+
+### Basic Search
+
+```python
+from fhir.resources.patient import Patient
+from fhir.resources.bundle import Bundle
+
+# Search by name
+search_params = {"family": "Smith", "given": "John"}
+results: Bundle = await gateway.search(Patient, search_params, "epic")
+
+for entry in results.entry:
+ patient = entry.resource
+ print(f"Found: {patient.name[0].family}, {patient.name[0].given[0]}")
+```
+
+### Advanced Search
+
+```python
+from fhir.resources.patient import Patient
+
+# Complex search with multiple parameters
+search_params = {
+ "birthdate": "1990-01-01",
+ "gender": "male",
+ "address-city": "Boston",
+ "_count": 50,
+ "_sort": "family"
+}
+
+results = await gateway.search(Patient, search_params, "epic")
+print(f"Found {len(results.entry)} patients")
+```
+
+## Transform Handlers π€
+
+Transform handlers allow you to create custom API endpoints that process and enhance FHIR resources with additional logic, AI insights, or data transformations before returning them to clients. These handlers run before the response is sent, enabling real-time data enrichment and processing.
+
+```python
+from fhir.resources.patient import Patient
+from fhir.resources.observation import Observation
+
+@fhir_gateway.transform(Patient)
+async def get_enhanced_patient_summary(id: str, source: str = None) -> Patient:
+ """Create enhanced patient summary with AI insights"""
+
+ async with fhir_gateway.modify(Patient, id, source=source) as patient:
+ # Get lab results and process with AI
+ lab_results = await fhir_gateway.search(
+ resource_type=Observation,
+ search_params={"patient": id, "category": "laboratory"},
+ source=source
+ )
+ insights = nlp_pipeline.process(patient, lab_results)
+
+ # Add AI summary
+ patient.extension = patient.extension or []
+ patient.extension.append({
+ "url": "http://healthchain.org/fhir/summary",
+ "valueString": insights.summary
+ })
+
+ return patient
+
+# The handler is automatically called via HTTP endpoint:
+# GET /fhir/transform/Patient/123?source=epic
+```
+
+## Aggregate Handlers π
+
+Aggregate handlers allow you to combine data from multiple FHIR sources into a single resource. This is useful for creating unified views across different EHR systems or consolidating patient data from various healthcare providers.
+
+
+```python
+from fhir.resources.observation import Observation
+from fhir.resources.bundle import Bundle
+
+@gateway.aggregate(Observation)
+async def aggregate_vitals(patient_id: str, sources: List[str] = None) -> Bundle:
+ """Aggregate vital signs from multiple sources."""
+ sources = sources or ["epic", "cerner"]
+ all_observations = []
+
+ for source in sources:
+ try:
+ results = await gateway.search(
+ Observation,
+ {"patient": patient_id, "category": "vital-signs"},
+ source
+ )
+ processed_observations = process_observations(results)
+ all_observations.append(processed_observations)
+ except Exception as e:
+ print(f"Could not get vitals from {source}: {e}")
+
+ return Bundle(type="searchset", entry=[{"resource": obs} for obs in all_observations])
+
+# The handler is automatically called via HTTP endpoint:
+# GET /fhir/aggregate/Observation?patient_id=123&sources=epic&sources=cerner
+```
+
+## Server Capabilities
+
+- **GET** `/fhir/metadata` - Returns FHIR-style `CapabilityStatement` of transform and aggregate endpoints
+- **GET** `/fhir/status` - Returns Gateway status and connection health
+
+
+## Connection Pool Management
+
+When you add a connection to a FHIR server, the gateway will automatically add it to a connection pool to manage connections to FHIR servers.
+
+
+### Pool Configuration
+
+```python
+# Create gateway with optimized connection settings
+gateway = FHIRGateway(
+ max_connections=100, # Total connections across all sources
+ max_keepalive_connections=20, # Keep-alive connections per source
+ keepalive_expiry=30.0, # Keep connections alive for 30 seconds
+)
+
+# Add multiple sources - they share the connection pool
+gateway.add_source("epic", "fhir://epic.org/...")
+gateway.add_source("cerner", "fhir://cerner.org/...")
+gateway.add_source("medplum", "fhir://medplum.com/...")
+
+stats = gateway.get_pool_status()
+print(stats)
+```
diff --git a/docs/reference/gateway/gateway.md b/docs/reference/gateway/gateway.md
new file mode 100644
index 00000000..6fc16773
--- /dev/null
+++ b/docs/reference/gateway/gateway.md
@@ -0,0 +1,105 @@
+# Gateway
+
+The HealthChain Gateway module provides a secure, asynchronous integration layer for connecting your NLP/ML pipelines with multiple healthcare systems. It provides a unified interface for connecting to FHIR servers, CDS Hooks, and SOAP/CDA services and is designed to be used in conjunction with the [HealthChainAPI](api.md) to create a complete healthcare integration platform.
+
+
+## Features π
+
+The Gateway handles the complex parts of healthcare integration:
+
+- **Multiple Protocols**: Works with [FHIR RESTful APIs](https://hl7.org/fhir/http.html), [CDS Hooks](https://cds-hooks.hl7.org/), and [Epic NoteReader CDI](https://discovery.hgdata.com/product/epic-notereader-cdi) (SOAP/CDA service) out of the box
+- **Multi-Source**: Context managers to work with data from multiple EHR systems and FHIR servers safely
+- **Smart Connections**: Handles [OAuth2.0 authentication](https://oauth.net/2/), connection pooling, and automatic token refresh
+- **Event-Driven**: Native [asyncio](https://docs.python.org/3/library/asyncio.html) support for real-time events, audit trails, and workflow automation
+- **Transform & Aggregate**: FastAPI-style declarative patterns to create endpoints for enhancing and combining data
+- **Developer-Friendly**: Modern Python typing and validation support via [fhir.resources](https://github.com/nazrulworld/fhir.resources) (powered by [Pydantic](https://docs.pydantic.dev/)), protocol-based interfaces, and informative error messages
+
+## Key Components
+
+| Component | Description | Use Case |
+|-----------|-------------|----------|
+| [**HealthChainAPI**](api.md) | FastAPI app with gateway and service registration | Main app that coordinates everything |
+| [**FHIRGateway**](fhir_gateway.md) | FHIR client with connection pooling and authentication| Reading/writing patient data from EHRs (Epic, Cerner, etc.) or application FHIR servers (Medplum, Hapi etc.) |
+| [**CDSHooksService**](cdshooks.md) | Clinical Decision Support hooks service | Real-time alerts and recommendations |
+| [**NoteReaderService**](soap_cda.md) | SOAP/CDA document processing service | Processing clinical documents and notes |
+| [**Event System**](events.md) | Event-driven integration | Audit trails, workflow automation |
+
+
+## Basic Usage
+
+
+```python
+from healthchain.gateway import HealthChainAPI, FHIRGateway
+from fhir.resources.patient import Patient
+
+# Create the application
+app = HealthChainAPI()
+
+# Create and configure a FHIR gateway
+fhir = FHIRGateway()
+
+# Connect to your FHIR APIs
+fhir.add_source("epic", "fhir://epic.org/api/FHIR/R4?client_id=...")
+fhir.add_source("medplum", "fhir://api.medplum.com/fhir/R4/?client_id=...")
+
+# Add AI enhancements to patient data
+@fhir.transform(Patient)
+async def enhance_patient(id: str, source: str = None) -> Patient:
+ async with fhir.modify(Patient, id, source) as patient:
+ patient.active = True # Your custom logic here
+ return patient
+
+# Register and run
+app.register_gateway(fhir)
+
+if __name__ == "__main__":
+ import uvicorn
+ uvicorn.run(app)
+
+# Default: http://127.0.0.1:8000/
+```
+
+You can also register multiple services of different protocols!
+
+```python
+from healthchain.gateway import (
+ HealthChainAPI, FHIRGateway,
+ CDSHooksService, NoteReaderService
+)
+
+app = HealthChainAPI()
+
+# FHIR for patient data
+fhir = FHIRGateway()
+fhir.add_source("epic", "fhir://fhir.epic.com/r4?...")
+
+# CDS Hooks for real-time alerts
+cds = CDSHooksService()
+
+@cds.hook("patient-view", id="allergy-alerts")
+def check_allergies(request):
+ # Your logic here
+ return {"cards": [...]}
+
+# SOAP for clinical documents
+notes = NoteReaderService()
+
+@notes.method("ProcessDocument")
+def process_note(request):
+ # Your NLP pipeline here
+ return processed_document
+
+# Register everything
+app.register_gateway(fhir)
+app.register_service(cds)
+app.register_service(notes)
+```
+
+
+## Protocol Support
+
+| Protocol | Implementation | Features |
+|----------|---------------|----------|
+| **FHIR API** | `FHIRGateway` | FHIR-instance level CRUD operations - [read](https://hl7.org/fhir/http.html#read), [create](https://hl7.org/fhir/http.html#create), [update](https://hl7.org/fhir/http.html#update), [delete](https://hl7.org/fhir/http.html#delete), [search](https://hl7.org/fhir/http.html#search), register `transform` and `aggregate` handlers, connection pooling and authentication management |
+| **CDS Hooks** | `CDSHooksService` | Hook Registration, Service Discovery |
+| **SOAP/CDA** | `NoteReaderService` | Method Registration (`ProcessDocument`), SOAP Service Discovery (WSDL)|
diff --git a/docs/reference/gateway/soap_cda.md b/docs/reference/gateway/soap_cda.md
new file mode 100644
index 00000000..89992e13
--- /dev/null
+++ b/docs/reference/gateway/soap_cda.md
@@ -0,0 +1,157 @@
+# SOAP/CDA Protocol
+
+The SOAP/CDA protocol enables real-time Clinical Documentation Improvement (CDI) services. This implementation follows the Epic-integrated NoteReader CDI specification for analyzing clinical notes and extracting structured data.
+
+## Overview
+
+Clinical Documentation workflows communicate using [CDA (Clinical Document Architecture)](https://www.hl7.org.uk/standards/hl7-standards/cda-clinical-document-architecture/). CDAs are standardized electronic documents for exchanging clinical information between different healthcare systems. They provide a common structure for capturing and sharing patient data like medical history, medications, and care plans between different healthcare systems and providers. Think of it as a collaborative Google Doc that you can add, amend, and remove entries from.
+
+The Epic NoteReader CDI is a SOAP/CDA-based NLP service that extracts structured data from clinical notes. Like CDS Hooks, it operates in real-time and is triggered when a clinician opts into CDI functionality and signs or pends a note.
+
+The primary use case for Epic NoteReader is to convert free-text medical documentation into coded information that can be used for billing, quality reporting, continuity of care, and clinical decision support at the point-of-care ([case study](https://www.researchsquare.com/article/rs-4925228/v1)).
+
+It is a vendor-specific component (Epic), but we plan to add support for other IHE SOAP/CDA services in the future.
+
+| When | Where | What you receive | What you send back |
+| :-------- | :-----| :-------------------------- |----------------------------|
+| Triggered when a clinician opts in to CDI functionality and signs or pends a note | EHR documentation modules (e.g. NoteReader in Epic) | A CDA document containing continuity of care data and free-text clinical notes | A CDA document with additional structured data extracted by your CDI service |
+
+## HealthChainAPI Integration
+
+Use the `NoteReaderService` with HealthChainAPI to handle SOAP/CDA workflows:
+
+```python
+from healthchain.gateway import HealthChainAPI, NoteReaderService
+from healthchain.models import CdaRequest, CdaResponse
+
+app = HealthChainAPI()
+notes = NoteReaderService()
+
+@notes.method("ProcessDocument")
+def process_note(request: CdaRequest) -> CdaResponse:
+ # Your NLP pipeline here
+ processed_document = nlp_pipeline.process(request)
+ return processed_document
+
+app.register_service(notes, path="/soap")
+```
+
+## Supported Workflows
+
+| Workflow Name | Description | Trigger | Status |
+|-----------|-------------|---------|----------|
+| `sign-note-inpatient` | CDI processing for inpatient clinical notes | Signing or pending a note in Epic inpatient setting | β
|
+| `sign-note-outpatient` | CDI processing for outpatient clinical notes | Signing or pending a note in Epic outpatient setting | β³ |
+
+Currently supports parsing of problems, medications, and allergies sections.
+
+## API Endpoints
+
+When registered with HealthChainAPI, the following endpoints are automatically created:
+
+| Endpoint | Method | Function | Protocol |
+|------|--------|----------|----------|
+| `/notereader/` | POST | `process_notereader_document` | SOAP |
+
+*Note: NoteReader is a vendor-specific component (Epic). Different EHR vendors have varying support for third-party CDI services.*
+
+## Request/Response Format
+
+### CDA Request Example
+
+```xml
+
+
+
+
+
+
+ - Hypertension
+
+
+
+
+
+
+
+
+
+
+
+ - Lisinopril 10 mg oral tablet, once daily
+
+
+
+
+
+
+
+
+```
+
+## Supported CDA Sections
+
+- **Problems/Conditions**: ICD-10/SNOMED CT coded diagnoses
+- **Medications**: SNOMED CT/RxNorm coded medications with dosage and frequency
+- **Allergies**: Allergen identification and reaction severity
+- **Progress Notes**: Free-text clinical documentation
+
+## Data Flow
+
+| Stage | Input | Output |
+|-------|-------|--------|
+| Gateway Receives | `CdaRequest` | Processed by your service |
+| Gateway Returns | Your processed result | `CdaResponse` |
+
+You can use the [CdaConnector](../pipeline/connectors/cdaconnector.md) to handle conversion between CDA documents and HealthChain pipeline data containers.
diff --git a/docs/reference/index.md b/docs/reference/index.md
index 8d405beb..3aa9afeb 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -2,6 +2,7 @@
## Core Components
+- [Gateway](gateway/gateway.md): Connect to multiple healthcare systems and services.
- [Pipeline](pipeline/pipeline.md): Build and manage processing pipelines for healthcare NLP and ML tasks.
- [Sandbox](sandbox/sandbox.md): Test your pipelines in a simulated healthcare environment.
- [Interoperability](interop/interop.md): Convert between healthcare data formats like FHIR, CDA, and HL7v2.
diff --git a/docs/reference/pipeline/components/cdscardcreator.md b/docs/reference/pipeline/components/cdscardcreator.md
index e0c35354..81cf46e7 100644
--- a/docs/reference/pipeline/components/cdscardcreator.md
+++ b/docs/reference/pipeline/components/cdscardcreator.md
@@ -127,4 +127,4 @@ pipeline.add_component(CdsCardCreator(
## Related Documentation
- [CDS Hooks Specification](https://cds-hooks.org/)
-- [Clinical Decision Support Documentation](../../sandbox/use_cases/cds.md)
+- [Clinical Decision Support Documentation](../../gateway/cdshooks.md)
diff --git a/docs/reference/pipeline/connectors/cdaconnector.md b/docs/reference/pipeline/connectors/cdaconnector.md
index 4a6ddda8..a6338470 100644
--- a/docs/reference/pipeline/connectors/cdaconnector.md
+++ b/docs/reference/pipeline/connectors/cdaconnector.md
@@ -4,7 +4,7 @@ The `CdaConnector` parses CDA documents, extracting free-text notes and relevant
This connector is particularly useful for clinical documentation improvement (CDI) workflows where a document needs to be processed and updated with additional structured data.
-[(Full Documentation on Clinical Documentation)](../../sandbox/use_cases/clindoc.md)
+[(Full Documentation on Clinical Documentation)](../../gateway/soap_cda.md)
## Input and Output
diff --git a/docs/reference/pipeline/connectors/cdsfhirconnector.md b/docs/reference/pipeline/connectors/cdsfhirconnector.md
index 2b49a86e..088dc8e4 100644
--- a/docs/reference/pipeline/connectors/cdsfhirconnector.md
+++ b/docs/reference/pipeline/connectors/cdsfhirconnector.md
@@ -2,7 +2,7 @@
The `CdsFhirConnector` handles FHIR data in the context of Clinical Decision Support (CDS) services, specifically using the [CDS Hooks specification](https://cds-hooks.org/).
-[(Full Documentation on Clinical Decision Support)](../../sandbox/use_cases/cds.md)
+[(Full Documentation on Clinical Decision Support)](../../gateway/cdshooks.md)
## Input and Output
diff --git a/docs/reference/pipeline/connectors/connectors.md b/docs/reference/pipeline/connectors/connectors.md
index 0f58651e..9e2f1463 100644
--- a/docs/reference/pipeline/connectors/connectors.md
+++ b/docs/reference/pipeline/connectors/connectors.md
@@ -23,8 +23,8 @@ Each connector can be mapped to a specific use case in the sandbox module.
| Connector | Use Case |
|-----------|----------|
-| `CdaConnector` | [**Clinical Documentation**](../../sandbox/use_cases/clindoc.md) |
-| `CdsFhirConnector` | [**Clinical Decision Support**](../../sandbox/use_cases/cds.md) |
+| `CdaConnector` | [**Clinical Documentation**](../../gateway/soap_cda.md) |
+| `CdsFhirConnector` | [**Clinical Decision Support**](../../gateway/cdshooks.md) |
## Adding connectors to your pipeline
diff --git a/docs/reference/pipeline/pipeline.md b/docs/reference/pipeline/pipeline.md
index e5df359c..20c64f42 100644
--- a/docs/reference/pipeline/pipeline.md
+++ b/docs/reference/pipeline/pipeline.md
@@ -15,7 +15,7 @@ HealthChain comes with a set of prebuilt pipelines that are out-of-the-box imple
| **QAPipeline** [TODO] | `Document` | N/A | A Question Answering pipeline suitable for conversational AI applications | Developing a chatbot to answer patient queries about their medical records |
| **ClassificationPipeline** [TODO] | `Tabular` | `CdsFhirConnector` | A pipeline for machine learning classification tasks | Predicting patient readmission risk based on historical health data |
-Prebuilt pipelines are end-to-end workflows with Connectors built into them. They interact with raw data received from EHR interfaces, usually CDA or FHIR data from specific [use cases](../sandbox/use_cases/use_cases.md).
+Prebuilt pipelines are end-to-end workflows with Connectors built into them. They interact with raw data received from EHR interfaces, usually CDA or FHIR data from specific [protocols](../gateway/gateway.md).
You can load your models directly as a pipeline object, from local files or from a remote model repository such as Hugging Face.
diff --git a/docs/reference/sandbox/client.md b/docs/reference/sandbox/client.md
deleted file mode 100644
index 50712925..00000000
--- a/docs/reference/sandbox/client.md
+++ /dev/null
@@ -1,50 +0,0 @@
-# Client
-
-A client is a healthcare system object that requests information and processing from an external service. This is typically an EHR system, but we may also support other health objects in the future such as a CPOE (Computerized Physician Order Entry).
-
-We can mark a client by using the decorator `@hc.ehr`. You must declare a particular **workflow** for the EHR client, which informs the sandbox how your data will be formatted. You can find more information on the [Use Cases](./use_cases/use_cases.md) documentation page.
-
-Data returned from the client should be wrapped in a [Prefetch](../../../api/data_models.md#healthchain.models.data.prefetch) object, where prefetch is a dictionary of FHIR resources with keys corresponding to the CDS service.
-
-You can optionally specify the number of requests to generate with the `num` parameter.
-
-=== "Clinical Documentation"
- ```python
- import healthchain as hc
-
- from healthchain.sandbox.use_cases import ClinicalDocumentation
- from healthchain.fhir import create_document_reference
-
- from fhir.resources.documentreference import DocumentReference
-
- @hc.sandbox
- class MyCoolSandbox(ClinicalDocumentation):
- def __init__(self) -> None:
- pass
-
- @hc.ehr(workflow="sign-note-inpatient", num=10)
- def load_data_in_client(self) -> DocumentReference:
- # Do things here to load in your data
- return create_document_reference(data="", content_type="text/xml")
- ```
-
-=== "CDS"
- ```python
- import healthchain as hc
-
- from healthchain.sandbox.use_cases import ClinicalDecisionSupport
- from healthchain.models import Prefetch
-
- from fhir.resources.patient import Patient
-
- @hc.sandbox
- class MyCoolSandbox(ClinicalDecisionSupport):
- def __init__(self) -> None:
- pass
-
- @hc.ehr(workflow="patient-view", num=10)
- def load_data_in_client(self) -> Prefetch:
- # Do things here to load in your data
- return Prefetch(prefetch={"patient": Patient(id="123")})
-
- ```
diff --git a/docs/reference/sandbox/sandbox.md b/docs/reference/sandbox/sandbox.md
deleted file mode 100644
index cff13b3d..00000000
--- a/docs/reference/sandbox/sandbox.md
+++ /dev/null
@@ -1,60 +0,0 @@
-# Sandbox
-
-Designing your pipeline to integrate well in a healthcare context is an essential step to turning it into an application that
-could potentially be adapted for real-world use. As a developer who has years of experience deploying healthcare NLP solutions into hospitals, I know how painful and slow this process can be.
-
-A sandbox makes this process easier. It provides a staging environment to debug, test, track, and interact with your application in realistic deployment scenarios without having to gain access to such environments, especially ones that are tightly integrated with local EHR configurations. Think of it as integration testing in healthcare systems.
-
-For a given sandbox run:
-
-1. Data is generated or loaded into a client (EHR)
-
-2. Data is wrapped and sent as standardized API requests the designated service
-
-3. Data is processed by the service (you application)
-
-4. Processed result is wrapped and sent back to the service as a standardized API response
-
-5. Data is received by the client which could be rendered in a UI interface
-
-To create a sandbox, initialize a class that inherits from a type of `UseCase` and decorate it with the `@hc.sandbox` decorator. `UseCase` loads in the blueprint of the API endpoints for the specified use case, and `@hc.sandbox` orchestrates these interactions.
-
-Every sandbox also requires a [**Client**](./client.md) function marked by `@hc.ehr` and a [**Service**](./service.md) function marked by `@hc.api`. Every client function must specify a **workflow** that informs the sandbox how your data will be formatted. For more information on workflows, see the [Use Cases](./use_cases/use_cases.md) documentation.
-
-!!! success "For each sandbox you need to specify..."
-
- - Use case
- - service function
- - client function
- - workflow of client
-
-
-```python
-import healthchain as hc
-
-from healthchain.pipeline import SummarizationPipeline
-from healthchain.sandbox.use_cases import ClinicalDecisionSupport
-from healthchain.data_generators import CdsDataGenerator
-from healthchain.models import CDSRequest, Prefetch, CDSResponse
-
-
-@hc.sandbox
-class MyCoolSandbox(ClinicalDecisionSupport):
- def __init__(self):
- self.data_generator = CdsDataGenerator()
- self.pipeline = SummarizationPipeline('gpt-4o')
-
- @hc.ehr(workflow="encounter-discharge")
- def load_data_in_client(self) -> Prefetch:
- prefetch = self.data_generator.generate_prefetch()
- return prefetch
-
- @hc.api
- def my_service(self, request: CDSRequest) -> CDSResponse:
- cds_response = self.pipeline(request)
- return cds_response
-
-if __name__ == "__main__":
- cds = MyCoolSandbox()
- cds.start_sandbox()
-```
diff --git a/docs/reference/sandbox/service.md b/docs/reference/sandbox/service.md
deleted file mode 100644
index 417a7117..00000000
--- a/docs/reference/sandbox/service.md
+++ /dev/null
@@ -1,66 +0,0 @@
-# Service
-
-A service is typically an API of a third-party system that returns data to the client, the healthcare provider object. This is where you define your application logic.
-
-When you decorate a function with `@hc.api` in a sandbox, the function is mounted standardized API endpoint an EHR client can make requests to. This can be defined by healthcare interoperability standards, such as HL7, or the EHR provider. HealthChain will start a [FastAPI](https://fastapi.tiangolo.com/) server with these APIs pre-defined for you.
-
-Your service function receives use case specific request data as input and returns the response data.
-
-We recommend you initialize your pipeline in the class `__init__` method.
-
-Here are minimal examples for each use case:
-
-=== "Clinical Documentation"
- ```python
- import healthchain as hc
-
- from healthchain.sandbox.use_cases import ClinicalDocumentation
- from healthchain.pipeline import MedicalCodingPipeline
- from healthchain.models import CdaRequest, CdaResponse
- from healthchain.fhir import create_document_reference
- from fhir.resources.documentreference import DocumentReference
-
- @hc.sandbox
- class MyCoolSandbox(ClinicalDocumentation):
- def __init__(self):
- self.pipeline = MedicalCodingPipeline.load("./path/to/model")
-
- @hc.ehr(workflow="sign-note-inpatient")
- def load_data_in_client(self) -> DocumentReference:
- with open('/path/to/data.xml', "r") as file:
- xml_string = file.read()
-
- return create_document_reference(data=xml_string, content_type="text/xml")
-
- @hc.api
- def my_service(self, request: CdaRequest) -> CdaResponse:
- response = self.pipeline(request)
- return response
- ```
-
-=== "CDS"
- ```python
- import healthchain as hc
-
- from healthchain.sandbox.use_cases import ClinicalDecisionSupport
- from healthchain.pipeline import SummarizationPipeline
- from healthchain.models import CDSRequest, CDSResponse, Prefetch
- from fhir.resources.patient import Patient
-
- @hc.sandbox
- class MyCoolSandbox(ClinicalDecisionSupport):
- def __init__(self):
- self.pipeline = SummarizationPipeline.load("model-name")
-
- @hc.ehr(workflow="patient-view")
- def load_data_in_client(self) -> Prefetch:
- with open('/path/to/data.json', "r") as file:
- fhir_json = file.read()
-
- return Prefetch(prefetch={"patient": Patient(**fhir_json)})
-
- @hc.api
- def my_service(self, request: CDSRequest) -> CDSResponse:
- response = self.pipeline(request)
- return response
- ```
diff --git a/docs/reference/sandbox/use_cases/cds.md b/docs/reference/sandbox/use_cases/cds.md
deleted file mode 100644
index 87b6ab0f..00000000
--- a/docs/reference/sandbox/use_cases/cds.md
+++ /dev/null
@@ -1,91 +0,0 @@
-# Use Cases
-
-## Clinical Decision Support (CDS)
-
-CDS workflows are based on [CDS Hooks](https://cds-hooks.org/). CDS Hooks is an [HL7](https://cds-hooks.hl7.org) published specification for clinical decision support. CDS hooks communicate using [FHIR (Fast Healthcare Interoperability Resources)](https://hl7.org/fhir/). For more information you can consult the [official documentation](https://cds-hooks.org/).
-
-| When | Where | What you receive | What you send back |
-| :-------- | :-----| :-------------------------- |----------------------------|
-| Triggered at certain events during a clinician's workflow, e.g. when a patient record is opened. | EHR | The context of the event and FHIR resources that are requested by your service. e.g. patient ID, `Encounter` and `Patient`. | βCardsβ displaying text, actionable suggestions, or links to launch a [SMART](https://smarthealthit.org/) app from within the workflow. |
-
-## Data Flow
-
-| Stage | Input | Output |
-|-------|-------|--------|
-| Client | N/A | `Prefetch` |
-| Service | `CDSRequest` | `CDSResponse` |
-
-
-[CdsFhirConnector](../../pipeline/connectors/cdsfhirconnector.md) handles the conversion of `CDSRequests` :material-swap-horizontal: `Document` :material-swap-horizontal: `CDSResponse` in a HealthChain pipeline.
-
-
-## Supported Workflows
-
-| Workflow Name | Description | Trigger | Maturity |
-|-----------|-------------|---------|----------|
-| `patient-view` | Triggered when a patient chart is opened | Opening a patient's chart | β
|
-| `order-select` | Triggered when a new order is selected | Selecting a new order | β³ |
-| `order-sign` | Triggered when orders are being signed | Signing orders | β³ |
-| `encounter-discharge` | Triggered when a patient is being discharged | Discharging a patient | β
|
-
-
-
-## Generated API Endpoints
-
-| Endpoint | Method | Function Name | API Protocol |
-|------|--------|----------|--------------|
-| `/cds-services` | GET | `cds_discovery` | REST |
-| `/cds-services/{id}` | POST | `cds_service` | REST |
-
-## What does the data look like?
-
-### Example `CDSRequest`
-
-```json
-{
- "hookInstance" : "23f1a303-991f-4118-86c5-11d99a39222e",
- "fhirServer" : "https://fhir.example.org",
- "hook" : "patient-view",
- "context" : {
- "patientId" : "1288992",
- "userId" : "Practitioner/example"
- },
- "prefetch" : {
- "patientToGreet" : {
- "resourceType" : "Patient",
- "gender" : "male",
- "birthDate" : "1925-12-23",
- "id" : "1288992",
- "active" : true
- }
- }
-}
-```
-### Example `CDSResponse`
-
-```json
-{
- "summary": "Bilirubin: Based on the age of this patient consider overlaying bilirubin [Mass/volume] results over a time-based risk chart",
- "indicator": "info",
- "detail": "The focus of this app is to reduce the incidence of severe hyperbilirubinemia and bilirubin encephalopathy while minimizing the risks of unintended harm such as maternal anxiety, decreased breastfeeding, and unnecessary costs or treatment.",
- "source": {
- "label": "Intermountain",
- "url": null
- },
- "links": [
- {
- "label": "Bilirubin SMART app",
- "url": "https://example.com/launch",
- "type": "smart"
- }
- ]
-}
-
-```
-
-## Implemented FHIR Resources
-
-- `Patient`
-- `Encounter`
-- `Procedure`
-- `MedicationRequest`
diff --git a/docs/reference/sandbox/use_cases/clindoc.md b/docs/reference/sandbox/use_cases/clindoc.md
deleted file mode 100644
index b2d2d59a..00000000
--- a/docs/reference/sandbox/use_cases/clindoc.md
+++ /dev/null
@@ -1,229 +0,0 @@
-# Clinical Documentation
-The `ClinicalDocumentation` use case implements a real-time Clinical Documentation Improvement (CDI) service. It currently implements the Epic-integrated NoteReader CDI specification, which communicates with a third-party NLP engine to analyse clinical notes and extract structured data. It helps convert free-text medical documentation into coded information that can be used for billing, quality reporting, continuity of care, and clinical decision support ([case study](https://www.researchsquare.com/article/rs-4925228/v1)).
-
-`ClinicalDocumentation` communicates using [CDA (Clinical Document Architecture)](https://www.hl7.org.uk/standards/hl7-standards/cda-clinical-document-architecture/). CDAs are standardized electronic documents for exchanging clinical information. They provide a common structure for capturing and sharing patient data like medical history, medications, and care plans between different healthcare systems and providers. Think of it as a collaborative Google Doc that you can add, amend, and remove entries from.
-
-| When | Where | What you receive | What you send back |
-| :-------- | :-----| :-------------------------- |----------------------------|
-| Triggered when a clinician opts in to a CDI functionality and signs or pends a note after writing it. | Specific modules in EHR where clinical documentation takes place, such as NoteReader in Epic. | A CDA document which contains continuity of care data and free-text data, e.g. a patient's problem list and the progress note that the clinician has entered in the EHR. | A CDA document which contains additional structured data extracted and returned by your CDI service. |
-
-
-## Data Flow
-
-| Stage | Input | Output |
-|-------|-------|--------|
-| Client | N/A | `DocumentReference` |
-| Service | `CdaRequest` | `CdaResponse` |
-
-
-[CdaConnector](../../pipeline/connectors/cdaconnector.md) handles the conversion of `CdaRequests` :material-swap-horizontal: `DocumentReference` :material-swap-horizontal: `CdaResponse` in a HealthChain pipeline.
-
-
-## Supported Workflows
-
-| Workflow Name | Description | Trigger | Maturity |
-|-----------|-------------|---------|----------|
-| `sign-note-inpatient` | Triggered when a clinician opts in to a CDI functionality and signs or pends a note after writing it in an inpatient setting. | Signing or pending a note in Epic | β
|
-| `sign-note-outpatient` | Triggered when a clinician opts in to a CDI functionality and signs or pends a note after writing it in an outpatient setting. | Signing or pending a note in Epic | β³ |
-
-We support parsing of problems, medications, and allergies sections, though some of the data fields may be limited. We plan to implement additional CDI services and workflows for different vendor specifications.
-
-## Generated API Endpoints
-
-| Endpoint | Method | Function | API Protocol |
-|------|--------|----------|--------------|
-| `/notereader/` | POST | `process_notereader_document` | SOAP |
-
-
-Note that NoteReader is a vendor-specific component (Epic). This particular note-based workflow is one type of CDI service. Different EHR vendors will have different support for third-party CDI services.
-
-## What does the data look like?
-### Example CDA Request
-
-```xml
-
-
-
-
-
-
- - Hypertension
-
-
-
-
-
-
-
- - Hypertension
-
-
-
-
-
-
-
- - Lisinopril 10 mg oral tablet, once daily
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Lisinopril 10 mg oral tablet
-
-
-
-
-
-
-
-