FHIR Server Architecture: Storage, Search, Scale and Build Options

Implementing the FHIR RESTful API means handling create, read, vread, update, patch, delete, history, search, batch and transaction interactions, plus whatever operations your use cases need. Behind that API, a production server typically contains:

• A resource store holding current and historical versions.
• A search index that extracts values for each supported search parameter.
• A validation layer that checks resources against base definitions and profiles.
• A terminology service for code validation and value set expansion.
• Security integration: an OAuth 2.0 authorization server, scope enforcement and audit (see FHIR security).
• Optional event and export pipelines for subscriptions and Bulk Data.
• A CapabilityStatement that accurately describes what the server supports.

For most teams the hybrid pattern is the pragmatic default. A pure relational model makes sense mainly when the FHIR API is a facade over an existing clinical database, in which case the challenge shifts to mapping and keeping the facade conformant.

FHIR search is expressive: string, token, reference, date, number, quantity, URI and composite parameter types, each with its own matching rules, modifiers such as :exact and :missing, prefixes such as ge and lt, chained and reverse-chained parameters, _include and _revinclude, sorting and paging. Each search parameter is defined by a FHIRPath expression that tells the indexer which values to extract.

• Index only the parameters your implementation guides require plus those your clients actually use; every index adds write cost.
• Date indexes must handle ranges and partial precision, because FHIR dates can be a year, a month or an instant.
• Token search needs both system and code, and many clients search by code alone, so index both forms.
• Paging should use stable cursors so results do not shift while a client is iterating.

FHIR treats each update as a new version with its own versionId, retrievable via vread and the _history interaction. Store versions immutably, support conditional updates with If-Match for optimistic locking, and decide your retention policy for history up front, because it can dominate storage growth.

Validation against profiles requires terminology: checking that a code belongs to a bound value set means expanding that value set, which may draw on large code systems such as SNOMED CT or LOINC. Servers either embed a terminology engine or call an external terminology server that implements operations like $expand, $validate-code, $lookup and $translate.

Full profile validation on every write is expensive. Common patterns are to validate synchronously at the API boundary for external writes, validate asynchronously for bulk loads, and cache value set expansions aggressively. Whatever you choose, be explicit in your documentation, because clients will assume that data returned by the server conforms to the profiles it advertises.

Event notification and population-level export both push work off the request path, so they need asynchronous infrastructure: a durable queue, workers and somewhere to stage output. Topic-based subscriptions, described in the R4 vs R5 guide, are easier to implement efficiently than R4 criteria-based subscriptions because the server defines the triggers.

The Bulk Data Access implementation guide defines $export at system, Patient and Group level. The client starts a job, polls a status URL and then downloads NDJSON files, one per resource type.

GET /fhir/Group/diabetes-cohort/$export?_type=Patient,Observation,Condition HTTP/1.1
Host: fhir.example.org
Accept: application/fhir+json
Prefer: respond-async
Authorization: Bearer eyJhbGciOi...

HTTP/1.1 202 Accepted
Content-Location: https://fhir.example.org/bulkstatus/7c1e2b

• Generate exports from a read replica or snapshot so they do not degrade transactional traffic.
• Stage output in object storage with short-lived, access-controlled download URLs.
• Support _since for incremental exports; it is what makes recurring population feeds affordable.

Platforms serving several organizations must decide how to isolate tenants. Options range from separate databases per tenant (strong isolation, more operational overhead) to partitioning within a shared database (efficient, but every query and index must be partition-aware) to logical separation through security labels or compartments (cheapest, riskiest). Tenant identity is often expressed in the base URL, which keeps references and CapabilityStatements clean.

• Keep the API tier stateless and scale it horizontally behind a load balancer.
• Scale reads with replicas and caching of conformance resources and terminology expansions.
• Watch transaction Bundles: large ones hold locks and can dominate write latency.
• Load-test with realistic search patterns, including _include and chained queries, not just simple reads.

Operational visibility deserves the same attention as throughput. Track latency and error rates per interaction type and per search parameter, not just per endpoint, so a single slow chained query does not hide inside an average. Log OperationOutcome issue codes, monitor queue depth for subscriptions and exports, and rehearse restores from backup, including history and search indexes, before you need them.

Few organizations should write a FHIR server from scratch. The real choice is between three paths, each with a different balance of control and effort:

Evaluate each against the same checklist: FHIR versions and implementation guides supported, search parameter coverage, SMART and Bulk Data support, subscriptions model, validation behaviour, tenancy, observability, backup and export of your own data. The FHIR server providers directory lists options, and teams that need a custom build can review FHIR server development services.