Clinical data aggregation: architecture that scales

A clinical data aggregation platform is an API layer that consolidates many clinical data sources behind a single, read-friendly contract. Downstream teams build against one typed SDK instead of a dozen origin APIs; source schema changes are absorbed at the hub; every request is budgeted and audited. It exists because the cost of clinical integration is never the first source, it is the twelfth, multiplied by every team that has to integrate it again.

The unaggregated state is easy to recognize because almost every healthcare data organization passes through it. Internal teams each hold credentials to several clinical systems. Each has reimplemented pagination, retry, and auth for each source. A source changes a payload and four consuming services break in four different sprints. Rate limits are hit by the sum of consumers no one coordinates. That was precisely the starting state before we built a clinical data aggregation hub: many sources, each with its own authentication, schema, and quirks, and every consumer paying the full integration tax separately.

The actual problem

Aggregation looks like a data problem and is actually a contract problem. Clinical sources disagree on everything contracts are made of: identity (which patient identifier is authoritative), shape (nested clinical documents vs flat claim rows), semantics (what "active" means for a medication in each system), pace (real-time APIs next to nightly batch drops), and reliability (systems that fail loudly next to systems that fail by returning stale data).

Every consuming team that integrates a source directly is forced to answer all five questions again, and their answers drift. Two internal services disagreeing about which medications are active is not a hypothetical; it is the default outcome of duplicated integration logic. The aggregation platform's real product is one set of answers, encoded in one contract, maintained in one place.

The hub pattern

The architecture that has survived production for us is a hub with three hard boundaries:

• Adapters own the sources. Each source connects through an adapter that translates its auth, schema, and quirks into the hub's internal model. Quirks stop at the adapter; nothing source-specific crosses into the hub core. Onboarding a new source is a hub-side adapter, not a change in any consumer.
• The contract owns the consumers. Consumers see one read-friendly API with one auth surface, and ideally build against a generated, typed SDK rather than raw HTTP. In our hub a typed C# SDK ships to downstream services, which turns integration from a project into a package reference.
• Versioning absorbs change. Endpoints version on schema. When a source changes, the adapter absorbs it; when the hub contract must change, a new version appears alongside the old one, and consumers migrate on their own schedule instead of in a coordinated emergency.

Two operational pieces complete the pattern. Request budgeting enforces fair use so one enthusiastic consumer cannot starve the rest or trip a source's rate limits on everyone's behalf. And request-level audit records who asked for what, when, which in a clinical context is not observability garnish but the answer to compliance questions that otherwise require archaeology across a dozen origin systems.

Designing the read contract

The temptation is to expose the union of everything every source offers. Resist it: the contract should be shaped by what consumers read, not by what sources contain. A read-friendly contract means flattened where consumers think flat, joined where consumers always join, and paginated in ways that map to real access patterns.

Where FHIR fits depends on your consumers. If they think in FHIR resources, and increasingly, teams downstream of USCDI-shaped exchange do, a FHIR facade is a natural contract. If they need flat read models for product features, forcing FHIR's nesting onto them recreates the problem the hub was meant to solve. The pattern is agnostic; the contract should follow the readers. What matters is that semantics are decided once: one definition of active medication, one authoritative patient identity, encoded in the hub instead of re-derived by every consumer.

Failure modes to design against

The hub becomes the bottleneck. Centralizing reads centralizes failure. The mitigations are boring and mandatory: replicas for heavy reads, caching with explicit staleness contracts, and budgets that shed load fairly under pressure.

Silent staleness. A source that stops updating while returning 200s will poison every consumer through the hub simultaneously. Freshness has to be a monitored property per source, with the hub surfacing data age in the contract rather than pretending everything is live.

Adapter leakage. The first time a source quirk is handled in hub core "just this once," the boundary is gone. Every subsequent source pays the complexity tax. Boundary discipline is cultural as much as technical, and it is cheaper to enforce from day one than to restore later.

Unbounded blast radius on schema change. If a hub contract change requires synchronized consumer releases, the hub has recreated point-to-point coupling with extra steps. Versioned endpoints and deprecation windows are the pressure valve.

When you need a warehouse instead

The hub answers what is true now, across sources, for operational reads. It does not answer what was true last quarter, and bolting history onto a live-read hub degrades both jobs. When the questions become longitudinal, quality measures over time, cohort analytics, regulatory reporting, the right tool is a clinical data warehouse: normalized history, idempotent ETL, replicas for analysts, like the one we describe in our warehouse case.

The two compose cleanly, hub for now, warehouse for history, and the hub's adapters often become the warehouse's cleanest feed. Which one first is a question of where the pain is: consumers re-integrating sources means hub first; analysts starved of history means warehouse first. Both builds, and the standards surface that usually feeds them, are the day job of our healthcare integration practice.