Blog/FHIR R4

Why Ilavrita Stores FHIR Binary Payloads Outside the Resource Row

Ilavrita Engineering · October 2, 2026

Why Ilavrita Stores FHIR Binary Payloads Outside the Resource Row

Primary query: FHIR Binary DocumentReference storage
Version: dev
Source revision: 7e036d413940d3978a5042409d387a4d52f2485c
FHIR version: R4 4.0.1
Data: synthetic only

Ilavrita remains a developer preview. Do not use patient data.

Last verified: October 2, 2026

FHIR makes a Binary look like a resource. Storage does not have to make its bytes look like an ordinary database field.

At the current Ilavrita revision, Binary payload bytes are stored outside the database row that describes the FHIR resource. DocumentReference can point to that Binary. The public contract stays FHIR; the storage boundary is an implementation choice.

Metadata and bytes have different operational needs

Ordinary FHIR JSON is useful to query, version and validate as structured data. A document payload may be megabytes of opaque bytes. Treating both identically couples database growth, backup behavior and file delivery to one storage mechanism.

Ilavrita separates them. The FHIR row retains the resource identity and metadata while the payload store owns the bytes.

This is not permission to bypass FHIR semantics. A Binary still has resource identity, versioning and authorization. Moving bytes outside the row must not create an unauthenticated file-server side door.

DocumentReference is the reference layer

The repository commit that introduced DocumentReference payload handling describes the intended relationship directly: keep a document's bytes in a Binary the reference names.

That gives an application two distinct concepts: the clinical/document metadata in DocumentReference and the opaque payload represented by Binary.

It also avoids inventing an Ilavrita-specific document object when FHIR already has the relevant resources.

External payload storage changes backup semantics

Once bytes and rows live in different stores, a database copy alone is not a complete backup. That is why Ilavrita's backup implementation snapshots the database and payload tree as one archive and verifies both.

The previous engineering note covered the backup ordering in detail. The important architectural consequence here is simpler: storage separation is useful, but every durability operation must understand both halves.

Authorization still belongs at the resource boundary

An external payload store is dangerous if knowing a filesystem path or object key is enough to retrieve clinical bytes.

Ilavrita's design keeps payload access behind the FHIR resource path and its authorization decisions. Storage location is not the access-control model.

That distinction will matter even more if the backend later changes from local disk to object storage.

What is proved, and what is not

Repository history at this revision contains the Binary external-payload implementation and DocumentReference-to-Binary handling. README also records Binary payloads as working.

This does not prove production readiness, encrypted object storage, virus scanning, DICOM support, or a complete document-management product. Those claims are outside the current evidence.

It also does not change the project-wide rule: synthetic data only.

Evidence

The useful boundary is this: FHIR defines what the resource means; Ilavrita's storage layer decides where its bytes live. Those should remain separate decisions.

Back to blog