# datasharingframework/dsf architecture

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

- Interactive diagram: https://gitdiagram.com/datasharingframework/dsf
- Repository: https://github.com/datasharingframework/dsf

## Overview

##### Project type and purpose
- This is a distributed full-stack microservice application (“Data Sharing Framework”) providing two core services at each site:
- A FHIR R4 server (dsf-fhir) exposing REST/WebSocket APIs for clinical resources.
- A BPMN-based process engine (dsf-bpe) coordinating local and cross-site workflows.
- The README confirms it uses Camunda (BPMN 2.0) and FHIR, secured via X.509 certificates, to support federated biomedical research.

##### High-level file structure
- Top-level modules:
- dsf-fhir (server, jetty, auth, REST adapter, validation)
- dsf-bpe (API, server, jetty)
- dsf-common (shared libraries: auth, config, db, UI, status)
- dsf-tools (CLI/build/db migration/documentation utilities)
- dsf-docker (Dockerfiles and docker-compose for multi-site deployment)
- dsf-webservice-client & websocket-client (client SDKs)
- Each service has sub-modules for Spring Boot / Jersey applications, configuration, resources (static/UI templates), database migrations (Liquibase), and test suites.

##### Key insights from README
- Each participating site deploys both the FHIR server and BPE engine in its local network.
- Services communicate over HTTPS with mutual X.509 authentication.
- Docker configurations orchestrate multiple “dic” sites, proxies, and a central trust provider (Keycloak for OIDC client configs).

1) FHIR Server (Spring Boot / Jersey + Jetty)
2) BPMN Process Engine (Camunda embedded in dsf-bpe)
3) Two Databases (PostgreSQL / Liquibase): one for FHIR data, one for BPMN engine & plugin state
4) Identity Provider (Keycloak or X.509 CA)
5) Reverse Proxy / API Gateway (Apache httpd or NGINX in dsf-docker)
6) External DSF Sites (peers with the same stack)
7) FHIR & WebSocket client libraries used by dsf-bpe and external apps
8) dsf-tools CLI utilities (db migrator, bundle generator, etc.)
- Incoming client requests → Proxy → FHIR Server or BPE Server
- BPE Server → (FHIR Webservice Client) → FHIR Server REST API
- FHIR Server publishes resource events → BPMN subscriptions or WebSocket clients
- Both servers ↔ Databases for persistence (JDBC / Liquibase migrations)
- Servers ↔ Identity Provider (mutual TLS or OIDC flows)
- Sites communicate peer-to-peer: BPE engines invoke remote FHIR endpoints for cross-site tasks
c. Architectural patterns and principles:
- Microservices: two bounded contexts (FHIR, BPE) with shared libraries via dsf-common
- Layered architecture:
– API layer (JAX-RS, Jersey, WebSocket)
– Service layer (Spring services, Camunda delegates)
– Data access (DAO, JDBC commands)
– Database migrations (Liquibase changelogs)
- Plugin pattern: dsf-bpe uses ProcessPluginApi to extend process tasks
- Event-driven: FHIR subscription events drive BPMN tasks
- Standardized deployments: Docker + docker-compose scripts for multisite setups
d. Technologies & frameworks (annotate components):
- Java 11+, Spring Boot, Jersey, Thymeleaf (UI templates)
- Camunda BPMN engine
- Jetty server, Log4j2 for logging
- Liquibase for DB migrations
- PostgreSQL (engine + identity)
- Maven for builds & GitHub Actions workflows
- Docker, NGINX/Apache, Keycloak for security

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Inbound Proxy Layer
    subgraph "Reverse Proxy / API Gateway"
        direction TB
        ProxyFHIR["FHIR Proxy\n(nginx/apache)"]:::infra
        ProxyBPE["BPE Proxy\n(nginx/apache)"]:::infra
    end

    %% Identity Provider
    Keycloak["Identity Provider\n(Keycloak / X.509 CA)"]:::infra

    %% Core Services Layer
    subgraph "Core Microservices"
        direction TB
        FHIRServer["FHIR Server\n(Spring Boot / Jersey + Jetty)"]:::fhir
        BPEServer["BPMN Process Engine\n(Camunda embedded)"]:::bpe
    end

    %% Shared Libraries
    subgraph "Shared Libraries (dsf-common)"
        direction TB
        AuthLib["Auth Library"]:::common
        ConfigLib["Config Library"]:::common
        DbLib["DB Library"]:::common
        JettyLib["Jetty Support"]:::common
        StatusLib["Status Library"]:::common
        UiLib["UI Library"]:::common
    end

    %% Clients & Tools
    subgraph "Clients & Utilities"
        direction TB
        FHIRClient["FHIR Webservice Client SDK"]:::tools
        WSClient["FHIR WebSocket Client SDK"]:::tools
        ToolsCLI["dsf-tools CLI & Utilities"]:::tools
    end

    %% Databases
    subgraph "Databases"
        direction TB
        FhirDB["PostgreSQL\nFHIR Data"]:::db
        BpeDB["PostgreSQL\nBPE & State"]:::db
    end

    %% Multi-site Orchestration
    subgraph "Multi-site Deployment (docker-compose)"
        direction TB
        dic1["dic1"]:::site
        dic2["dic2"]:::site
        dic3["dic3"]:::site
        ttp["ttp"]:::site
        meshProxy["Mesh Proxy"]:::infra
    end

    %% Flows
    ProxyFHIR -->|"HTTPS/TLS"| FHIRServer
    ProxyBPE -->|"HTTPS/TLS"| BPEServer

    FHIRServer -->|JDBC / Liquibase| FhirDB
    BPEServer -->|JDBC / Liquibase| BpeDB

    BPEServer -->|"FHIR R4 REST"| FHIRServer
    FHIRServer -->|"WebSocket events"| WSClient
    FHIRServer -->|"Subscription events"| BPEServer

    FHIRServer -->|"OAuth2/OIDC or MTLS"| Keycloak
    BPEServer -->|"OAuth2/OIDC or MTLS"| Keycloak

    FHIRClient -->|"calls REST"| FHIRServer
    WSClient -->|"subscribes WS"| FHIRServer

    ToolsCLI -->|"DB migrations"| FhirDB
    ToolsCLI -->|"DB migrations"| BpeDB
    ToolsCLI -->|"Proxy tests"| ProxyFHIR
    ToolsCLI -->|"Proxy tests"| ProxyBPE

    %% Peer-to-peer cross-site calls
    BPEServer --- dic1
    BPEServer --- dic2
    BPEServer --- dic3
    BPEServer --- ttp

    %% Click Events
    click FHIRServer "https://github.com/datasharingframework/dsf/tree/main/dsf-fhir/dsf-fhir-server"
    click FHIRServer "https://github.com/datasharingframework/dsf/tree/main/dsf-fhir/dsf-fhir-server-jetty"
    click BPEServer "https://github.com/datasharingframework/dsf/tree/main/dsf-bpe/dsf-bpe-server"
    click BPEServer "https://github.com/datasharingframework/dsf/tree/main/dsf-bpe/dsf-bpe-server-jetty"
    click BPEServer "https://github.com/datasharingframework/dsf/tree/main/dsf-bpe/dsf-bpe-process-api-v1"
    click AuthLib "https://github.com/datasharingframework/dsf/tree/main/dsf-common/dsf-common-auth"
    click ConfigLib "https://github.com/datasharingframework/dsf/tree/main/dsf-common/dsf-common-config"
    click DbLib "https://github.com/datasharingframework/dsf/tree/main/dsf-common/dsf-common-db"
    click JettyLib "https://github.com/datasharingframework/dsf/tree/main/dsf-common/dsf-common-jetty"
    click StatusLib "https://github.com/datasharingframework/dsf/tree/main/dsf-common/dsf-common-status"
    click UiLib "https://github.com/datasharingframework/dsf/tree/main/dsf-common/dsf-common-ui"
    click ProxyFHIR "https://github.com/datasharingframework/dsf/tree/main/dsf-docker/fhir_proxy"
    click ProxyBPE "https://github.com/datasharingframework/dsf/tree/main/dsf-docker/bpe_proxy"
    click Keycloak "https://github.com/datasharingframework/dsf/tree/main/dsf-docker-test-setup-3dic-ttp/keycloak"
    click dic1 "https://github.com/datasharingframework/dsf/tree/main/dsf-docker-test-setup-3dic-ttp/dic1"
    click dic2 "https://github.com/datasharingframework/dsf/tree/main/dsf-docker-test-setup-3dic-ttp/dic2"
    click dic3 "https://github.com/datasharingframework/dsf/tree/main/dsf-docker-test-setup-3dic-ttp/dic3"
    click ttp "https://github.com/datasharingframework/dsf/tree/main/dsf-docker-test-setup-3dic-ttp/ttp"
    click meshProxy "https://github.com/datasharingframework/dsf/tree/main/dsf-docker-test-setup-3dic-ttp/proxy"
    click FHIRClient "https://github.com/datasharingframework/dsf/tree/main/dsf-fhir/dsf-fhir-webservice-client"
    click WSClient "https://github.com/datasharingframework/dsf/tree/main/dsf-fhir/dsf-fhir-websocket-client"
    click ToolsCLI "https://github.com/datasharingframework/dsf/tree/main/dsf-tools/dsf-tools-build-info-reader"
    click ToolsCLI "https://github.com/datasharingframework/dsf/tree/main/dsf-tools/dsf-tools-bundle-generator"
    click ToolsCLI "https://github.com/datasharingframework/dsf/tree/main/dsf-tools/dsf-tools-db-migration"
    click ToolsCLI "https://github.com/datasharingframework/dsf/tree/main/dsf-tools/dsf-tools-default-ca-files-generator"
    click ToolsCLI "https://github.com/datasharingframework/dsf/tree/main/dsf-tools/dsf-tools-docker-secrets-reader"
    click ToolsCLI "https://github.com/datasharingframework/dsf/tree/main/dsf-tools/dsf-tools-documentation-generator"
    click ToolsCLI "https://github.com/datasharingframework/dsf/tree/main/dsf-tools/dsf-tools-proxy-test"
    click ToolsCLI "https://github.com/datasharingframework/dsf/tree/main/dsf-tools/dsf-tools-test-data-generator"

    %% Styles
    classDef fhir fill:#a2d5f2,stroke:#0288d1,color:#000;
    classDef bpe fill:#c2f784,stroke:#558b2f,color:#000;
    classDef db fill:#ffcc80,stroke:#e65100,color:#000;
    classDef infra fill:#ce93d8,stroke:#6a1b9a,color:#000;
    classDef common fill:#b0bec5,stroke:#455a64,color:#000;
    classDef tools fill:#cfd8dc,stroke:#37474f,color:#000;
    classDef site fill:#eeeeee,stroke:#9e9e9e,color:#000;
```
