Adrian Bernhard
← Technical docs

Overview

FHIR Sandbox: technical overview

How a simulated Swiss hospital, radiology institute and patient portal fit together on FHIR R4, FHIR R5 and DICOMweb, and why they are built this way.

Updated 26 October 2026

1. What it is#

The FHIR Sandbox is a small simulated Swiss care setting: a hospital (Erebor), an independent radiology institute (Orthanc) and a patient portal (Imladris). Each runs as its own system with its own patient IDs, its own API and, in the institutions' case, its own FHIR version. They are built on real standards (HL7 FHIR R4 and R5, DICOM and DICOMweb) and hold curated, fictional demo patients: eight Swiss showcase patients who exist at both institutions, plus a few hundred Synthea-generated patients at the hospital. The images are real, openly licensed research studies relabelled to the fictional patients. Everything is public to read, so the APIs can be tried with a browser or curl.

flowchart LR
    V[Visitor's browser]
    subgraph IM[Imladris: patient portal]
        IAPI[Portal API]
        IDB[(Accounts and links only)]
    end
    subgraph ER[Erebor: hospital]
        EF[FHIR R4 API]
        ED[Front desk]
    end
    subgraph OR[Orthanc: radiology]
        OD[DICOMweb]
        OF[RIS, FHIR R5]
        ODK[Front desk]
    end
    V --> IAPI
    IAPI --- IDB
    IAPI -->|FHIR R4| EF
    IAPI -->|QIDO-RS + FHIR R5| OD & OF
    V -->|WADO-RS images| OD
    V -.->|popup| ED & ODK
    ED & ODK -->|institution key| IAPI

Erebor and Orthanc know nothing about each other. Imladris is the only place a patient's records from both are shown together, and only for institutions the patient has linked.

2. The systems#

Erebor, the hospital. Role: the clinical record (stays, diagnoses, procedures, letters, lab and pathology reports, appointments). Stack: HAPI FHIR 8.12 JPA server on PostgreSQL 16, behind a small Node/Express gateway that also serves a patient-file explorer and the hospital's front desk. Standard: FHIR R4. URL: https://fhir.adrianbernhard.ch (API at /fhir). Details: Erebor technical doc.

Orthanc, the radiology institute. Role: a PACS (image archive) and a small RIS (patient registry, orders, radiology reports). Stack: Orthanc 1.13 with its DICOMweb plugin and a HAPI-based FHIR plugin, PostgreSQL 16 for the index, and a Node/Express gateway that adds the RIS as a FHIR facade, a browse UI with a Cornerstone3D viewer, and the institute's front desk. Standards: DICOM, DICOMweb (QIDO-RS, WADO-RS), FHIR R5. URL: https://dicom.adrianbernhard.ch. Details: Orthanc technical doc.

Imladris, the patient portal. Role: lets a patient link their records at each institution and view them in one timeline, with an inline DICOM viewer. Stores accounts and link state, no clinical data. Stack: Node/Express, PostgreSQL 16, plain HTML/CSS/JS, Cornerstone3D for the viewer. Standards: consumes FHIR R4 (Erebor), FHIR R5 and DICOMweb (Orthanc). URL: https://portal.adrianbernhard.ch. Details: Imladris technical doc.

3. How data moves#

Linking a patient#

A patient in Imladris asks to link an institution. Imladris issues a short single-use code and opens that institution's own front desk in a popup on the institution's domain. The desk, not Imladris, decides who the patient is.

sequenceDiagram
    actor P as Patient
    participant I as Imladris
    participant D as Institution front desk
    participant R as Institution records
    P->>I: Link Erebor (or Orthanc)
    I->>I: issue code (10 min, single use), store only its hash
    I->>D: open popup /desk?code=XXXX-XXXX
    D->>I: lookup code (institution key)
    I-->>D: claimed name, birth date, demo AHV
    D->>R: find matching patients
    D->>D: staff pick a patient
    D->>I: lookup again
    D->>R: read the chosen patient
    D->>D: compare identity server-side
    D->>I: redeem: own patient ID + match level and differing field names
    I->>I: store link (account, institution, external ID)
    D-->>P: postMessage "done", close popup
    P->>I: poll own server for the code's status

The identity check runs on the institution's server from a fresh lookup, so the browser cannot choose the result. The result is match, differences (a name differs, or an AHV number is missing on one side) or mismatch (birth date or AHV differs; needs an explicit confirmation). Only field names travel, never values. Both institutions run a byte-identical copy of the same identity module, so they grade matches the same way. The postMessage is only a nudge: Imladris treats its own server as the source of truth.

Opening the dashboard#

sequenceDiagram
    actor P as Browser
    participant I as Imladris server
    participant E as Erebor (FHIR R4)
    participant O as Orthanc (DICOMweb + FHIR R5)
    P->>I: dashboard summary
    I-->>P: account + linked institutions (database only)
    par one event stream per institution
        P->>I: events for Erebor
        I->>E: 5 searches + Patient read, _count=200, client key
        E-->>I: Bundles
        I-->>P: normalized timeline events
    and
        P->>I: events for Orthanc
        I->>O: QIDO-RS studies + RIS DiagnosticReport, Patient, Practitioner
        O-->>I: DICOM JSON + R5 Bundles
        I-->>P: normalized timeline events
    end
    P->>I: open a letter or report
    I->>E: read one document (live, no-store)
    I-->>P: sanitized HTML
    P->>O: WADO-RS series metadata and frames (browser, no key)

Each institution streams over its own Server-Sent Events connection, so one slow or starting institution never blocks the other. Erebor's searches cover conditions, encounters, documents, diagnostic reports and upcoming appointments. For Orthanc, Imladris finds studies with QIDO-RS and reads reports, the registration and radiologists from the R5 RIS; it does not use Orthanc's FHIR ImagingStudy. The R4 and R5 clients share no FHIR code on purpose, so assumptions from one version cannot leak into the other. Pixel data never passes through Imladris: the viewer fetches it from Orthanc's DICOMweb endpoint in the browser.

When an institution restarts#

After a deploy or Erebor's nightly reset, HAPI needs a minute or two to start and warm up. Erebor's gateway answers during that time instead of failing:

sequenceDiagram
    participant I as Imladris
    participant G as Erebor gateway
    participant H as HAPI
    G->>H: poll /metadata until it answers
    I->>G: FHIR search
    G-->>I: 503, Retry-After: 30, "starting up"
    I-->>I: card shows a neutral "starting up" notice, one automatic retry
    G->>H: warm-up: Imladris's own query shapes, one at a time
    G->>G: ready
    I->>G: retry
    G-->>I: 200 Bundle

Imladris treats a 503 from any institution as "starting", per institution and never as an error. Orthanc currently has no readiness gate and no /health endpoint, so it does not send this signal yet.

Radiology orders between Erebor and Orthanc: not built#

There is no order or report flow between the hospital and the institute. Orthanc's orders exist only as completed ServiceRequests registered together with the images, linked to images and reports by accession number inside Orthanc. Erebor's own radiology reports are part of its curated data, not received from Orthanc. Modelling the ordering side is listed as a possible next step.

4. Standards and identifiers#

FHIR R4 vs R5. Erebor runs unmodified HAPI FHIR on R4. Orthanc's FHIR API is R5 because its FHIR plugin is built on HAPI R5; Orthanc's gateway serves the RIS resources itself and proxies the plugin's DICOM-derived resources under one /fhir path. The mismatch is kept on purpose: real institutions do not upgrade in lockstep, and a portal has to cope with that. It shows up concretely, for example DiagnosticReport.study (R5) versus imagingStudy (R4). Neither server declares or validates against a profile such as CH Core.

DICOMweb. Orthanc's official plugin provides QIDO-RS (search) and WADO-RS (retrieve). Imladris uses QIDO-RS server-side and WADO-RS from the browser. STOW-RS and classic DIMSE are not reachable from outside.

Identifiers. Each institution has its own: Erebor MRNs (EB plus 8 digits), Orthanc patient IDs (OR- plus 5 digits) and accession numbers, each under an identifier system on its own domain. The one shared identifier is a demo AHV number, system https://fhir.adrianbernhard.ch/sid/ahv-demo. Real AHV numbers start with 756 and have their own OID; the demo numbers use neither and start with 999, and Imladris's database refuses anything else. Two curated patients have no AHV on file at Orthanc and some names are spelled differently there (Lea vs Léa, Ruegg vs Rüegg), on purpose, to exercise the fallback match on name and birth date. In the real Swiss EPD the cross-community identifier is the EPR-SPID, not the AHV number; the demo AHV is a simplification.

Why Imladris stores no clinical data. The portal's job is to mediate access, not to become a third copy of the record. It stores who the patient is, which institutions they linked, each institution's patient ID and the match verdict. Every clinical item is read live when the patient looks at it and never cached. Removing a link leaves nothing behind. Functionally, the links table plays the role of an IHE PIX cross-reference, created by a patient's consented action instead of a matching algorithm.

5. Security model#

The same principles run through all three systems:

  • Fictional data only. No real patients; demo AHV numbers cannot collide with real ones. Openness is the point of the demo, and nothing here would be public in practice.
  • Gateways are the only way in. HAPI, the Orthanc server and the databases have no public port. Orthanc additionally keeps its own authentication on behind the gateway, which injects the credential and strips client headers.
  • Open reads, keyed writes. Reads need no credentials. Writes need a write key that only the seeding and curation scripts hold, compared in constant time. Even with the key, only a short list of writes is allowed.
  • Allowlists, not blocklists. Erebor forwards only three read-only FHIR operations; Orthanc forwards only an explicit list of read paths, which keeps its admin UI and bulk downloads out of reach, and refuses every FHIR operation.
  • Rate limits per IP, in memory, with tighter budgets for expensive queries and a larger one for the image viewer's frame requests.
  • Client keys between the apps. Imladris (and this portfolio's live stats) read for many visitors from one IP, so each sends its own X-Client-Key to each institution. A client key only lifts the rate limits: no writes, no extra operations. Each key goes only to its own server, server-side, and can be revoked alone.
  • Institution keys for the desk. Each institution's front desk authenticates to Imladris with its own key, server to server. Imladris's institution API refuses any request that looks like it came from a browser.
  • Link codes are short-lived, single-use, stored only as a keyed hash, limited in failed attempts, and every invalid code gets the same answer.
  • Untrusted text. Documents are writable by design, so every system renders Markdown server-side with raw HTML, links and images off, then sanitizes to a structural tag allowlist with no attributes.
  • Headers. A strict Content-Security-Policy everywhere (no inline script), HSTS, nosniff, no X-Powered-By. The desks and the portal choose their opener policies so the linking popup keeps its connection to the portal.
  • No sensitive logs. Codes, identities, keys and document text are never logged.

There is no user authentication anywhere: anyone can pick any demo account in Imladris, and the front desks have no staff login.

6. Operations#

  • Hosting. All three systems run on one VPS (4 GB RAM) under Coolify. Each repository is a Docker Compose stack that redeploys on every push to main; Coolify terminates TLS.
  • Nightly resets. At 03:00 UTC Erebor restores a clean database snapshot (restored into a temporary database first, then swapped in), so anything written during the day disappears. At 03:15 UTC Imladris restores every demo account's links to the seed. Orthanc has no reset; its data changes only through keyed curation uploads.
  • Pinned demo dates. The curated data is anchored at 2026-10-03, and Imladris pins the same anchor for the demo accounts' birth dates. The tooling can shift dates in whole weeks on a rebuild, but no shared, scheduled rebuild exists yet.
  • Readiness and warm-up. Erebor's gateway starts immediately, answers 503 starting until HAPI is up, then warms HAPI's caches with the exact queries the portal and this site send before opening. It falls back to "starting" if HAPI drops out.
  • Memory. HAPI's heap is capped below its container limit (the JVM otherwise sized itself from host RAM and swapped); Orthanc has a 1 GiB limit sized from local measurements. The gateways and Imladris have no limits.

7. Design decisions and trade-offs#

A small gateway in front of HAPI and Orthanc. Access rules (open reads, keyed writes, allowlists, rate limits, readiness) live in a few dozen lines of Express instead of custom Java interceptors or Orthanc plugins. Trade-off: the gateway sees HTTP, not FHIR semantics; it can refuse an operation but cannot inspect what a transaction would touch.

A FHIR facade instead of a second FHIR server at Orthanc. A second HAPI instance for the RIS would not fit in memory, so Orthanc's gateway serves a validated R5 Bundle from memory and merges in the plugin's resources. Trade-off: hand-written search semantics, no _include, no history.

Imladris reads live and copies nothing. No stale data, nothing to purge on unlink, and the portal stays honest about who holds the record. Trade-off: every dashboard load hits both institutions, and an institution that is down shows an empty card.

The institution vouches, the portal records. Identity proofing happens at the desk of whoever holds the record, on their own domain. Trade-off: Imladris must trust the desk's patient ID and match verdict; it validates their shape strictly but cannot check them, and shows "not checked" rather than assuming a match.

Pinned demo dates. All three systems must agree on birth dates, or the desk reports a mismatch for a correct person. Pinning one shared anchor keeps them consistent until they can move together. Trade-off: "upcoming" appointments drift into the past until the shared weekly shift exists.

FHIR R5 kept at Orthanc. It comes with the official plugin and gives the portal a real cross-version problem. Trade-off: two FHIR clients with no shared code.

8. Known limits and what's next#

Limits: no authentication, consent resource or audit log; SMART on FHIR is not implemented; one shared write key per institution; rate limits are per IP and in memory; no profile validation; matching uses a demo AHV number rather than an EPR-SPID; Orthanc has no readiness signal; demo dates are pinned; there is no ordering workflow between the hospital and the institute.

Next: a shared weekly date shift across all three systems, the Eregion apps on this site that demonstrate FHIR mechanics, health checks for Orthanc, CH Core profiles for the curated patients, SMART on FHIR as a second auth demonstration, and possibly an order flow from Erebor to Orthanc.

9. Using the sandbox for testing#

Free to read for testing and learning. Every patient is synthetic, there is no real patient data. The images are openly licensed, de-identified research studies from the NCI Imaging Data Commons (TCIA and Zenodo collections), relabelled to the fictional patients. The full source list is at https://dicom.adrianbernhard.ch/credits.

Public read endpoints

System Standard Base URL
Erebor FHIR R4 https://fhir.adrianbernhard.ch/fhir
Orthanc DICOMweb (QIDO-RS, WADO-RS) https://dicom.adrianbernhard.ch/dicom-web
Orthanc RIS FHIR R5 https://dicom.adrianbernhard.ch/fhir
sh
curl "https://fhir.adrianbernhard.ch/fhir/Patient?_summary=count"
curl "https://fhir.adrianbernhard.ch/fhir/Patient?identifier=https://fhir.adrianbernhard.ch/sid/ahv-demo|999.4001.0000.19"
curl "https://dicom.adrianbernhard.ch/dicom-web/studies?PatientID=OR-60394"

Rules of the road

  • Read only. Writes need a key and aren't available.
  • Rate limits per IP: about 2 requests per second (120 per minute) on each server. $everything is capped at 10 per minute, whole-study or whole-series image retrieves at 20 per minute. A shared network, like a campus, counts as one IP and shares one limit. Over it you get 429 with Retry-After.
  • Erebor resets every night at 03:00 UTC and answers 503 for a minute or two while it restarts. Server ids can change, so search by identifier (MRN or demo AHV) instead of hard-coding ids. Orthanc has no nightly reset.
  • For repeated tests, export once with Patient/{id}/$everything (follow the next links) and work offline.
  • Browser apps are fine: CORS allows any origin on both servers.

Run your own. Need data permanently, or want to write? It is all open source: HAPI FHIR with Synthea for the hospital, Orthanc with public datasets such as TCIA for imaging.

Need something else? Use the contact form.