# trifork/hapi-fhir-export-client architecture

> Architecture diagram of the GitHub repository trifork/hapi-fhir-export-client, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/trifork/hapi-fhir-export-client
- Repository: https://github.com/trifork/hapi-fhir-export-client

## Overview

##### Main Components
- Client Configuration & Setup: Represent the initial configuration where the user creates the FHIR context (e.g., FhirContext for R4) and an HttpClient instance. This component includes the setup of interceptors, security, and parsers.
- Export Request Builder: Illustrate the BDExportRequest along with its associated parameters (e.g., output format, resource types, filters via BDExportTypeFilter). Show how the request encapsulates all the options needed for a Bulk Data Export.
- Export Clients: There are two concrete implementations (ApacheHttpClient4BDExportClient and ApacheHttpClient5BDExportClient) that implement the common BDExportClient interface or functionality. These clients initiate and resume exports.
- Export Response and Output Processing: Capture the flow where a BDExportResponse/BDExportResultResponse is returned upon export completion. Illustrate how BDExportConverter converts these responses, fetching the underlying FHIR Binary resources and handling output and error streams.
- Testing & Utility Components: Although less critical for the runtime design, you might note the existence of integration and unit tests (located in src/test) that validate the functionality of the export client and its components.

##### Relationships and Data Flow
- Start at the Client Configuration layer: A user instantiates FhirContext and HttpClient → these are passed to create a BDExportClient instance.
- The user then constructs a BDExportRequest using builder patterns that include type filters and query parameters.
- This request is handed over to the BDExportClient (or specific instances of ApacheHttpClient4/5BDExportClient) via a method such as startExport().
- The future is eventually polled (or resumed via resumeExport) using a polling URI, which eventually yields a BDExportResponse.
- The response, containing either data or error information, is then processed by BDExportConverter to create a structured BDExportResourceResult with actual FHIR Binary data.
- Finally, a user (or consuming service) fetches and handles the export result (data and errors) as needed.

##### Architectural Patterns and Principles
- Layered Architecture: Separate concerns between configuration, request construction, export initiation, asynchronous handling, and output parsing.
- Asynchronous Processing: Clearly note the future pattern used in handling long-running export operations.
- Extensibility: Identify how the use of multiple HTTP client implementations (version 4 and 5) demonstrates flexibility in supporting underlying transport differences.
- Error Handling: Represent that error responses and cancellation flows are explicitly managed, which is crucial for long-running processes.

##### Technologies, Frameworks, and Tools
- Java with Maven for dependency management (pom.xml).
- Use of HAPI FHIR libraries (seen in code samples) for FHIR context and client operations.
- Apache HttpClient implementations (versions 4 and 5) for making HTTP calls.
- Logging configuration via log4j2 (from src/main/resources/log4j2.xml).
- Docker deployment hints (deploy.sh and docker-compose.yaml) indicating preparation for containerized deployment.
- Unit and integration tests (located under src/test).

- That every component described in the README is captured.
- To address the asynchronous nature of the export with appropriate branching for “success” and “error” scenarios.
- Clear separation of responsibilities: configuration/setup, export initiation, asynchronous waiting/polling, and response parsing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Layer
    subgraph "Configuration Layer"
        Config["FHIR Context & HttpClient Setup"]
    end

    %% Request Building Layer
    subgraph "Request Building Layer"
        Req1["BDExportRequest"]
        Req2["BDExportTypeFilter"]
    end

    %% Client Execution Layer
    subgraph "Client Execution Layer"
        ClientIntf["BDExportClient interface"]
        Apache4["ApacheHttpClient4BDExportClient"]
        Apache5["ApacheHttpClient5BDExportClient"]
    end

    %% Asynchronous Handling Layer
    subgraph "Asynchronous Handling Layer"
        Future["BDExportFuture"]
        Initiated["BDInitiatedExportFuture"]
        Failed["BDFailedExportFuture"]
    end

    %% Response Processing Layer
    subgraph "Response Processing Layer"
        Resp["BDExportResponse"]
        Result["BDExportResultResponse"]
        Converter["BDExportConverter"]
    end

    %% External FHIR Endpoint
    External["External FHIR BulkDataExport Endpoint"]

    %% Testing & Utility Components
    subgraph "Testing & Utility Components"
        TestExport["Export Tests (src/test/java/com/trifork/ehealth/export)"]
        TestResponse["Response Tests (src/test/java/com/trifork/ehealth/export/response)"]
    end

    %% Flow Connections
    Config -->|"configures"| ClientIntf
    Req2 -->|"filter"| Req1
    Req1 -->|"buildsRequest"| ClientIntf

    ClientIntf -->|"impl"| Apache4
    ClientIntf -->|"impl"| Apache5

    Apache4 -->|"sendReq"| External
    Apache5 -->|"sendReq"| External

    Apache4 -->|"startExport"| Future
    Apache5 -->|"startExport"| Future

    Future -->|"onSuccess"| Initiated
    Future -->|"onError"| Failed

    Initiated -->|"yieldsRes"| Resp
    Failed -->|"yieldsRes"| Resp

    Resp -->|"convert"| Converter
    Converter -->|"processed"| Result

    %% Click Events for Component Mapping
    click Req1 "https://github.com/trifork/hapi-fhir-export-client/blob/main/src/main/java/com/trifork/ehealth/export/BDExportRequest.java"
    click Req2 "https://github.com/trifork/hapi-fhir-export-client/blob/main/src/main/java/com/trifork/ehealth/export/BDExportTypeFilter.java"
    click ClientIntf "https://github.com/trifork/hapi-fhir-export-client/blob/main/src/main/java/com/trifork/ehealth/export/BDExportClient.java"
    click Apache4 "https://github.com/trifork/hapi-fhir-export-client/blob/main/src/main/java/com/trifork/ehealth/export/ApacheHttpClient4BDExportClient.java"
    click Apache5 "https://github.com/trifork/hapi-fhir-export-client/blob/main/src/main/java/com/trifork/ehealth/export/ApacheHttpClient5BDExportClient.java"
    click Future "https://github.com/trifork/hapi-fhir-export-client/blob/main/src/main/java/com/trifork/ehealth/export/future/BDExportFuture.java"
    click Initiated "https://github.com/trifork/hapi-fhir-export-client/blob/main/src/main/java/com/trifork/ehealth/export/future/BDInitiatedExportFuture.java"
    click Failed "https://github.com/trifork/hapi-fhir-export-client/blob/main/src/main/java/com/trifork/ehealth/export/future/BDFailedExportFuture.java"
    click Resp "https://github.com/trifork/hapi-fhir-export-client/blob/main/src/main/java/com/trifork/ehealth/export/response/BDExportResponse.java"
    click Result "https://github.com/trifork/hapi-fhir-export-client/blob/main/src/main/java/com/trifork/ehealth/export/response/BDExportResultResponse.java"
    click Converter "https://github.com/trifork/hapi-fhir-export-client/blob/main/src/main/java/com/trifork/ehealth/export/BDExportConverter.java"
    click TestExport "https://github.com/trifork/hapi-fhir-export-client/tree/main/src/test/java/com/trifork/ehealth/export"
    click TestResponse "https://github.com/trifork/hapi-fhir-export-client/tree/main/src/test/java/com/trifork/ehealth/export/response"

    %% Styles
    class Config blue
    class Req1,Req2,ClientIntf,Apache4,Apache5 green
    class Future,Initiated,Failed,Resp,Converter,Result orange
    class External gray
    class TestExport,TestResponse green
```
