Healthcare platform teams debate frameworks while production clinics drown in duplicate patient rows. The failure mode is predictable: scheduling mints identifier A, the chart opens B, and every HL7 ORU or FHIR DiagnosticReport becomes a reconciliation ticket. Fixing that is not a bigger bus — it is a stricter identity model before you publish the first REST endpoint.
Patient as the spine, not the payload
FHIR’s Patient resource is often treated as metadata wrapped around real work. In clinic platforms it should be the aggregate root: Encounters, ServiceRequests, Observations and DiagnosticReports reference one internal UUID mapped to a stable external identifier. HL7 v2 can remain at the edge; the monolith must not allow second writers to fork identity.
Bounded contexts still matter — appointments, clinical documentation, orders, billing — but they share an identity service with idempotent create and merge rules. Nightly deduplication jobs are an admission that write paths were wrong on day one.
Events clinicians can trust
Batch reconciliation felt acceptable when results arrived next morning. In-clinic workflows need Observation and DiagnosticReport events propagated as soon as validation completes, subscribed by the encounter service holding the active visit. Cron-driven uploads are a latency bug measured in patient minutes, not job duration.
The FHIR Patient resource specification is explicit about identifiers; your tenancy model should mirror that discipline internally before exposing interoperability facades.
Modular monolith beats interface sprawl
Microservice fashion encouraged best-of-breed sprawl. Healthcare punishes sprawl because shared concepts must stay consistent or safety erodes. A modular monolith on one tenant trades theoretical isolation for one transaction boundary around the visit that orders, receives and bills.
Promed HIS implements that clinically — engineers evaluating stacks should score how many user stories still need a paid transform after licence signature. Overview for readers outside the repo: medical office software; UK deployment notes: medical practice management software uk.
Architecture review prompts
- Exactly one patient UUID per human per tenant?
- Order events keyed for idempotent consumption by lab adapters?
- External FHIR/HL7 endpoints read-only replicas — not alternate writers?
- Encounter timeline replayable without cross-database joins?
- Contract tests on outbound profiles when regional labs change segments?
Observability should trace encounters, not only HTTP status codes. Support should answer missing-result tickets with event IDs and timestamps — not shrugs about last night’s batch.
Terminology and versioned maps
SNOMED, LOINC and local code sets evolve. Internal models need versioned concept maps with effective dates so historical encounters stay interpretable while new orders use current coding. Terminology services belong at the edge; the monolith owns the truth clinicians see in the room.
Schema migrations on clinical tables should survive rolling upgrades — maintenance windows are rare in busy clinics. Feature flags must default safe on prescribing paths; experimental modules stay off critical routes until proven.
Load, tenancy and replay
Multi-site groups need tenant isolation with shared policy templates. Lab adapters must tolerate duplicate deliveries without double-charting — key on order and accession, not arrival order alone. Morning rush simulations (concurrent bookings, result floods, prescribing checks) are safety load tests, not optional perf tickets.
Medical office platforms fail in the mapping layer before the UI. Fix Patient identity and event flow first; framework debates second.
Anti-patterns to delete early
Separate patient tables per module. Results tables keyed only on national identifier without encounter context. Outbound feeds that write back into clinical tables on ACK. Shadow “staging” charts for integrations that never graduate. Each pattern feels expedient in sprint zero; each becomes a permanent tax.
Prefer strangler migrations behind feature flags: new encounters on the unified model, legacy read-only until retired. Big-bang cutovers in live clinics fail loudly at the worst hours — Monday 08:00.
Developer experience is clinician experience
When your internal APIs cannot answer “show me everything that happened in encounter X,” clinicians will never trust the UI built on top. Invest in encounter-scoped integration tests that simulate order → result → prescribe loops using production-like fixtures — not only unit tests on serializers.
Documentation for platform teams should include partner onboarding playbooks with sample messages and expected projections — reducing the tribal knowledge trapped in one integration engineer’s notebook.
Run quarterly game days that simulate lab partner outages and duplicate ORU bursts. If on-call cannot restore encounter visibility within agreed minutes, your architecture is still batch-shaped — regardless of microservice count.
Top comments (0)