r-squared

r-squared is the reference data service for the dataLOFT platform. It demonstrates how a domain-specific healthcare data service integrates with the management services to enable data discovery, contract negotiation, and transfer between two independent organisations.

Purpose

r-squared implements an ECG (electrocardiogram) analysis workflow. A clinic captures ECG patient data, publishes it as a discoverable data product, and a second party negotiates access, retrieves the files, and runs an analysis job on them. This mirrors a real cross-institutional use case: a data holder that produces clinical data and a specialised service provider that processes it, without either side giving up control over the exchange.

Architecture

r-squared is a Gradle multi-module project (Kotlin/Quarkus):

Module	Description
common	Shared utilities and domain models.
ecg-gateway	Entry point for the data service. Handles incoming requests and coordinates the other modules. It also exposes the gRPC admin API used to seed demo data.
ecg-analyzer-service	Quarkus microservice that manages ECG analysis jobs. Jobs progress through the states: QUEUED → RUNNING → DONE / FAILED. Uses a PostgreSQL backend via Hibernate Reactive.
clinical-ui	Web interface for clinicians to browse datasets and interact with analysis results.

When deployed, an r-squared instance runs as a set of pods — clinical-ui, ecg-gateway, ecg-analyzer, and a fhir-server that holds the clinical records in the FHIR interoperability format.

Integration with management services

r-squared does not speak the Dataspace Protocol itself. Instead it implements the run-dsrpc gRPC provider interface and delegates all dataspace communication to a RUN-DSP connector:

• RUN-DSP calls into r-squared to serve catalogue responses and dataset information.
• When a consumer initiates a transfer, RUN-DSP instructs r-squared to provide download access.

This is the same integration contract any data service uses (see Data services): implement run-dsrpc, register offerings in FC-Service, and let the management services handle identity, negotiation, and transfer.

r-squared is deployed in the demo namespace in both the staging and production clusters of the hosted dataLOFT platform.

The dataLOFT demo scenario

The reference demo wires r-squared into a complete data space with two independent participants exchanging data end-to-end over the Dataspace Protocol:

• Edge plays the data holder — for example a clinic that captures ECG patient data. Its r-squared-edge instance publishes the ECG datasets as data products.
• Cloud plays the data service provider — for example a cloud-based ECG analysis service. Its r-squared-cloud instance consumes the datasets and offers analysis in return.

Each participant is self-contained and runs its own stack:

• an r-squared instance (the domain data service),
• a connector (RUN-DSP plus the rdsp-s3 provider backend) that negotiates contracts and serves or consumes data over the Dataspace Protocol,
• a signature auth handler (Signature-Auth-Handler + HST-DID) that signs and verifies Dataspace Protocol messages and hosts the participant's did:web document (see the auth subsystem),
• a contracting system (Reference Contract Service) that manages the contract negotiation.

Three services are shared by both participants:

• the Federated Catalog (fed-cat), which makes both participants' data products discoverable through federated metadata,
• the Dataspace Portal, which handles participant onboarding, registration, and verification against the catalogue,
• an Identity Provider (Keycloak), which authenticates the end users of the participants' applications (clinicians logging into the clinical UI) via OIDC. It is deliberately not involved in dataspace-protocol or participant identity — that is handled by the did:web / signature-auth-handler flow. It is shared here only to keep the demo simple.

At a high level the exchange runs: the Cloud participant discovers the Edge participant's ECG datasets through the Federated Catalog, negotiates a contract through the two connectors, transfers the data over the Dataspace Protocol, and then runs the analysis.

No consent flow yet

The current demo runs without data owner consent. There is no Consent Management App (CMA) integration in this scenario: the contracting systems auto-approve every negotiation (contracts are treated as default-verified). It demonstrates institution-to-institution data sharing directly between a provider and a consumer.

Future demo scenarios will add consent flows using the Consent Management App, demonstrating the full data sovereignty capability of the platform.

Running the demo yourself

The helm-deployment repository is a hands-on, step-by-step guide to standing up this exact scenario on your own Kubernetes cluster. Where these docs explain the architecture, that repo gets a running instance of it up so you can watch the exchange work. It uses plain helm and kubectl commands you run and inspect one at a time — not a one-shot installer — so every piece is visible.

What you end up with

Both the Edge and Cloud participant from the demo scenario, simulated in a single cluster and running together in one dataspace-demo namespace. Because both participants live in the same cluster, the demo can take a shortcut that a real cross-organisation deployment cannot: instead of exchanging root CAs between clusters, all internal gRPC traffic is secured by one shared mTLS root CA, from which cert-manager issues a leaf certificate per service.

How it is built up

The guide deploys in layers, each depending on the one before it:

1. Generic Kubernetes infrastructure every service needs: cert-manager (TLS certificates via Let's Encrypt DNS-01 challenges), an Ingress controller, and the CloudNativePG operator for the databases.
2. An mTLS root CA for the internal gRPC traffic between connectors, bootstrapped once and distributed to the dataspace-demo namespace by trust-manager.
3. fed-cat on its own, deployed first as a single, end-to-end run through the whole certificate and ingress flow before the larger demo is layered on top.
4. The full two-participant demo: an S3-compatible object store (rustfs) as the data backend, then for each participant the connector stack (run-dsp, rdsp-s3, contract service, signature-auth-handler), Keycloak, and finally the r-squared instances and a birds-eye-view dashboard.

Once everything is running, the guide walks through seeding demo ECG data into the Edge gateway and registering both participants in the Federated Catalog so they can discover each other.

A declarative alternative

The repository also ships a Helmfile that pins every chart version and encodes the same install order, so the Kubernetes infrastructure can be brought up with a single helmfile sync. The step-by-step path is recommended the first time through, because it makes each layer and its checks explicit.

See the helm-deployment README for the full walkthrough, including prerequisites, per-step verification, and teardown.