# dotimplement/healthchain architecture

> Architecture diagram of the GitHub repository dotimplement/healthchain, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dotimplement/healthchain
- Repository: https://github.com/dotimplement/healthchain

## Overview

##### Project Type and Purpose
- HealthChain is an open-source, modular Python SDK and API framework for healthcare AI integration.
- It provides:
– A unified Gateway layer to connect to FHIR servers, CDS Hooks, and SOAP/CDA endpoints.
– A Pipeline framework for NLP/ML workflows on healthcare data.
– An InteropEngine for template-based conversions (CDA ↔ FHIR ↔ HL7v2).
– Synthetic Data Generators and a Sandbox for testing.
– A FastAPI-based HealthChainAPI for hosting services in production.

##### File Structure & Key Modules
- healthchain/gateway:
– API layer (FastAPI app, endpoints)
– Protocol implementations (FHIR, CDS Hooks, SOAP/CDA)
– Client pools, connection management, event dispatchers
- healthchain/interop:
– ConfigManager, Engines (parsers, generators, template registry)
- healthchain/pipeline:
– Pipeline DSL, preprocessor/postprocessor components, model-router, built-in pipelines
- healthchain/data_generators & healthchain/utils:
– Synthetic data templates, Pydantic validation, helpers
- healthchain/sandbox & cli:
– Sandbox harness, workflow decorators, environment injection, CLI entrypoint
- healthchain/service & healthchain/cli:
– HealthChainAPI assembly, service registration, command-line interface

##### README Insights
- Emphasizes event-driven, asynchronous architecture (FastAPI + async clients).
- Pydantic models enforce type safety.
- Liquid/Jinja template engine for Interop.

##### Main Components & Their Interactions
– Registers Gateways (FHIRGateway, CDSHooksService, NoteReaderService)
– Exposes REST endpoints (/fhir/*, /cds/*, /soap/*) via FastAPI
B. Gateway Layer
– FHIRGateway
- Client Pool → external FHIR servers
- Transform hooks (Patient, Observation, etc.)
– CDSHooksService
- Hook definitions → AI logic → returns cards
– NoteReaderService (SOAP)
- WSGI server → accepts CDA XML → dispatch to Interop/Pipelines
C. InteropEngine
– Parsers (CDA XML to intermediate objects)
– Generators (FHIR JSON to CDA, HL7v2)
– Template Registry loading YAML/liquid templates
D. Pipeline Framework
– Data Containers (Document, Tabular)
– Nodes: Preprocessor → NLP model (spaCy, HF) → Postprocessor
– Connectors: CdaConnector, CdsFhirConnector
– Pre-built Pipelines: MedicalCodingPipeline, SummarizationPipeline
E. Synthetic Data & Sandbox
– DataGenerators: Patient, Condition, Medication, Encounter…
– Sandbox UseCase classes + decorators → generate realistic EHR data
– CLI (“healthchain run …”) to spin up sandbox environments
F. External Systems & ML Models
– External EHRs (FHIR servers, CDS Hooks endpoints, SOAP/CDA services)
– AI/ML Models (spaCy, HuggingFace Transformers)

##### Architectural Patterns & Design Principles
- Modular, plugin-based: each protocol, parser, generator, pipeline component is pluggable.
- Event-driven & async: gateways dispatch events to handlers, pipelines process data asynchronously.
- Template-based interop: Liquid templates for format conversion.
- Type safety: Pydantic models for FHIR resources and internal data structures.
- Separation of concerns: API layer, core engine, data layer, ML components, sandbox.

## Diagram (Mermaid)

```mermaid
graph TB
    %% HealthChain API Layer
    subgraph "HealthChainAPI" 
        direction TB
        API_Service["HealthChainAPI Service"]:::core
        API_Endpoints["API Endpoints (/fhir, /cds, /soap)"]:::core
        API_App["FastAPI App"]:::core
    end

    %% Gateway Layer
    subgraph "Gateway Layer"
        direction TB
        FHIR_Gateway["FHIRGateway"]:::core
        CDSHooks_Service["CDSHooksService"]:::core
        NoteReader_Service["NoteReaderService (SOAP/CDA)"]:::core
    end

    %% Interop Engine
    subgraph "InteropEngine"
        direction TB
        Engine["Engine"]:::core
        ConfigMgr["ConfigManager"]:::core
        Parsers["Parsers (CDA, base)"]:::core
        Generators["Generators (CDA, FHIR)"]:::core
        TemplateRegistry["TemplateRegistry & Models"]:::core
    end

    %% Pipeline Framework
    subgraph "Pipeline Framework"
        direction TB
        Pipeline_Core["Pipeline Core & DSL"]:::core
        ModelRouter["ModelRouter"]:::core
        Preprocessor["Preprocessor"]:::core
        NLP_Model["NLP Model (spaCy, HF)"]:::external
        Postprocessor["Postprocessor"]:::core
        Connectors["Connectors (CdaConnector, CdsFhirConnector)"]:::core
        PreBuiltPipes["Pre-built Pipelines"]:::core
    end

    %% Synthetic Data & Utilities
    subgraph "Data Generators & Utils"
        direction TB
        DataGenerators["DataGenerators"]:::util
        ValueSets["ValueSets"]:::util
        Utilities["Helper Utilities"]:::util
    end

    %% Sandbox & CLI
    subgraph "Sandbox & CLI"
        direction TB
        Sandbox_Harness["Sandbox Harness"]:::core
        Sandbox_Env["Environment"]:::core
        Sandbox_Clients["Sandbox Clients"]:::core
        Sandbox_UseCases["Sandbox UseCases"]:::core
        Sandbox_Decorators["Workflow Decorators"]:::core
        CLI["CLI Entrypoint"]:::core
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        FHIR_Server["FHIR Server"]:::external
        CDSHooks_Endpoint["CDS Hooks Endpoint"]:::external
        SOAP_Endpoint["SOAP/CDA Endpoint"]:::external
        ML_Store["ML Model Store"]:::external
    end

    %% Configuration & Templates
    subgraph "Configs & Templates"
        direction TB
        Global_Configs["Global Configs (YAML)"]:::util
        Interop_Templates["Interop Templates"]:::util
    end

    %% Connections
    API_Service -->|registers| FHIR_Gateway
    API_Service -->|registers| CDSHooks_Service
    API_Service -->|registers| NoteReader_Service
    API_Endpoints -->|routes to| API_App

    FHIR_Server -->|async requests| FHIR_Gateway
    CDSHooks_Endpoint -->|hook events| CDSHooks_Service
    SOAP_Endpoint -->|CDA XML| NoteReader_Service

    FHIR_Gateway -->|transform| Engine
    CDSHooks_Service -->|AI logic| NLP_Model
    NoteReader_Service -->|dispatch| Pipeline_Core

    Engine -->|uses| Parsers
    Engine -->|uses| Generators
    Engine -->|loads| TemplateRegistry
    Engine -->|reads configs| ConfigMgr

    Pipeline_Core -->|routes via| ModelRouter
    ModelRouter -->|calls| Preprocessor
    Preprocessor -->|invoke| NLP_Model
    NLP_Model -->|results| Postprocessor
    Postprocessor -->|output via| Connectors
    Connectors -->|write to| FHIR_Gateway

    Connectors -->|input| Pipeline_Core
    ML_Store -->|hosts models| NLP_Model

    CLI -->|launches| Sandbox_Harness
    Sandbox_Harness -->|setup| Sandbox_Env
    Sandbox_Env -->|uses| DataGenerators
    Sandbox_Env -->|uses| ValueSets
    Sandbox_Env -->|uses| Utilities
    Sandbox_Harness -->|invokes| Sandbox_UseCases
    Sandbox_UseCases -->|decorated by| Sandbox_Decorators
    Sandbox_Clients -->|simulate| FHIR_Server

    Global_Configs -->|provide| ConfigMgr
    Interop_Templates -->|feeds| TemplateRegistry

    %% Click Events
    click API_Service "https://github.com/dotimplement/healthchain/blob/main/healthchain/service/service.py"
    click API_Endpoints "https://github.com/dotimplement/healthchain/blob/main/healthchain/service/endpoints.py"
    click API_App "https://github.com/dotimplement/healthchain/blob/main/healthchain/gateway/api/app.py"

    click FHIR_Gateway "https://github.com/dotimplement/healthchain/blob/main/healthchain/gateway/core/fhirgateway.py"
    click FHIR_Gateway "https://github.com/dotimplement/healthchain/blob/main/healthchain/gateway/clients/fhir.py"
    click FHIR_Gateway "https://github.com/dotimplement/healthchain/blob/main/healthchain/gateway/events/fhir.py"

    click CDSHooks_Service "https://github.com/dotimplement/healthchain/blob/main/healthchain/gateway/protocols/cdshooks.py"
    click CDSHooks_Service "https://github.com/dotimplement/healthchain/blob/main/healthchain/gateway/events/cdshooks.py"

    click NoteReader_Service "https://github.com/dotimplement/healthchain/blob/main/healthchain/gateway/soap/wsgi.py"
    click NoteReader_Service "https://github.com/dotimplement/healthchain/blob/main/healthchain/gateway/soap/epiccdsservice.py"
    click NoteReader_Service "https://github.com/dotimplement/healthchain/blob/main/healthchain/gateway/events/notereader.py"

    click Engine "https://github.com/dotimplement/healthchain/blob/main/healthchain/interop/engine.py"
    click ConfigMgr "https://github.com/dotimplement/healthchain/blob/main/healthchain/interop/config_manager.py"
    click Parsers "https://github.com/dotimplement/healthchain/blob/main/healthchain/interop/parsers/cda.py"
    click Parsers "https://github.com/dotimplement/healthchain/blob/main/healthchain/interop/parsers/base.py"
    click Generators "https://github.com/dotimplement/healthchain/blob/main/healthchain/interop/generators/cda.py"
    click Generators "https://github.com/dotimplement/healthchain/blob/main/healthchain/interop/generators/fhir.py"
    click TemplateRegistry "https://github.com/dotimplement/healthchain/blob/main/healthchain/interop/template_registry.py"
    click TemplateRegistry "https://github.com/dotimplement/healthchain/tree/main/healthchain/interop/models/"

    click Pipeline_Core "https://github.com/dotimplement/healthchain/blob/main/healthchain/pipeline/base.py"
    click Pipeline_Core "https://github.com/dotimplement/healthchain/blob/main/healthchain/pipeline/pipeline.py"
    click ModelRouter "https://github.com/dotimplement/healthchain/blob/main/healthchain/pipeline/modelrouter.py"
    click Preprocessor "https://github.com/dotimplement/healthchain/blob/main/healthchain/pipeline/components/preprocessors.py"
    click Postprocessor "https://github.com/dotimplement/healthchain/blob/main/healthchain/pipeline/components/postprocessors.py"
    click PreBuiltPipes "https://github.com/dotimplement/healthchain/blob/main/healthchain/pipeline/medicalcodingpipeline.py"
    click PreBuiltPipes "https://github.com/dotimplement/healthchain/blob/main/healthchain/pipeline/summarizationpipeline.py"
    click Connectors "https://github.com/dotimplement/healthchain/blob/main/healthchain/io/cdaconnector.py"
    click Connectors "https://github.com/dotimplement/healthchain/blob/main/healthchain/io/cdsfhirconnector.py"
    click Connectors "https://github.com/dotimplement/healthchain/blob/main/healthchain/io/containers/document.py"
    click Connectors "https://github.com/dotimplement/healthchain/blob/main/healthchain/io/containers/tabular.py"

    click DataGenerators "https://github.com/dotimplement/healthchain/tree/main/healthchain/data_generators/"
    click ValueSets "https://github.com/dotimplement/healthchain/tree/main/healthchain/data_generators/value_sets/"
    click Utilities "https://github.com/dotimplement/healthchain/blob/main/healthchain/utils/idgenerator.py"
    click Utilities "https://github.com/dotimplement/healthchain/blob/main/healthchain/utils/utils.py"

    click Sandbox_Harness "https://github.com/dotimplement/healthchain/blob/main/healthchain/sandbox/base.py"
    click Sandbox_Env "https://github.com/dotimplement/healthchain/blob/main/healthchain/sandbox/environment.py"
    click Sandbox_Clients "https://github.com/dotimplement/healthchain/blob/main/healthchain/sandbox/clients/ehr.py"
    click Sandbox_UseCases "https://github.com/dotimplement/healthchain/tree/main/healthchain/sandbox/use_cases/"
    click Sandbox_Decorators "https://github.com/dotimplement/healthchain/blob/main/healthchain/sandbox/decorator.py"
    click Sandbox_Decorators "https://github.com/dotimplement/healthchain/blob/main/healthchain/sandbox/workflows.py"
    click Sandbox_Env "https://github.com/dotimplement/healthchain/blob/main/healthchain/sandbox/utils.py"
    click CLI "https://github.com/dotimplement/healthchain/blob/main/healthchain/cli.py"

    click Global_Configs "https://github.com/dotimplement/healthchain/blob/main/configs/defaults.yaml"
    click Interop_Templates "https://github.com/dotimplement/healthchain/tree/main/configs/interop/"
    click Interop_Templates "https://github.com/dotimplement/healthchain/tree/main/configs/templates/cda_fhir/"
    click Interop_Templates "https://github.com/dotimplement/healthchain/tree/main/configs/templates/fhir_cda/"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,color:#154360
    classDef external fill:#A9DFBF,stroke:#145A32,color:#196F3D
    classDef util fill:#D5D8DC,stroke:#566573,color:#2C3E50
```
