Architecture for Healthcare Software

What is a healthcare software architecture?

A healthcare software architecture is the arrangement of a health product's applications, services, integrations, data stores and infrastructure, together with the rules for how patient data moves between them. A good one keeps protected health information inside known boundaries, records every access, survives outages of partner systems and lets teams change one part without breaking the others.

Architecture is not the same as the tech stack. The stack is the list of products and frameworks. The architecture is the shape: which parts exist, what each one owns, how they talk and what happens when one of them fails.

The reference model in this guide is a starting point, not a template to copy whole. A small patient app may collapse several layers into one service. A multi-site clinical platform will split them further. The questions each layer answers stay the same.

Which quality attributes drive the design?

Healthcare architecture is driven less by raw scale and more by auditability, availability during care hours, interoperability and privacy. Rank these with the product owner before choosing patterns, because they pull in different directions.

• Auditability: Every read and change of patient data can be traced to a person or system, a time and a reason.
• Availability in care hours: A clinic that cannot check patients in at 8 a.m. stops working, so planned maintenance and failover are designed around clinical schedules.
• Interoperability: Data moves in and out through standard formats such as HL7 v2, HL7 FHIR and X12, without custom work for every new partner.
• Privacy by structure: The design limits where PHI can go, rather than relying on every developer to remember.
• Safety: A clinical value is never silently changed, truncated or shown without its unit and context.
• Changeability: Payer rules, code sets and partner interfaces change often, so the parts that change most are isolated from those that change least.

Write the ranking down. When a later decision trades one attribute for another, such as caching patient data on a device for availability at the cost of privacy, the ranking settles the argument.

How do you lay out the architecture layer by layer?

Lay it out in seven layers from the user down: experience, edge and identity, domain services, workflow and events, integration, data, and platform. Each layer depends only on the layers below it, and each has a clear owner.

• 1. Experience: Clinician web apps, patient mobile apps, admin consoles and partner portals. They hold no business rules and no long-lived patient data, only what the current screen needs.
• 2. Edge and identity: The API gateway, web application firewall, identity provider and authorization server. Every request is authenticated here, and SMART on FHIR or OAuth scopes are checked before anything reaches a service.
• 3. Domain services: Scheduling, clinical records, orders, billing, messaging and consent, each owning its own data and rules. Split them by business area, not by technical function.
• 4. Workflow and events: A task engine for multi-step work handed between staff over hours or days, such as referral review, and an event bus that announces each change to the services that care about it.
• 5. Integration: An interface engine for HL7 v2, a FHIR API for partners and apps, X12 connections through a clearinghouse and adapters for vendor APIs. Partner formats are translated here and never leak into domain services.
• 6. Data: Operational databases for each service, a separate append-only audit store, document and image storage, and an analytics store fed by de-identified or access-controlled copies.
• 7. Platform: Cloud accounts, networks, encryption keys, backups, the CI and deployment pipeline and observability. It sits under everything, and it is where recovery is built.

Two rules keep the layers honest. Experience apps call the edge layer only, never a database or an internal service directly. Integration translates every partner format to the product's own model, so a change at one hospital touches one adapter, not every service.

Where should the PHI boundary sit?

Draw the PHI boundary as tightly as the product allows, around the domain services, the integration layer and the operational and audit data stores. Everything outside it, such as marketing sites, product analytics, error tracking and most developer tools, should receive no identifiable patient data.

Make the boundary physical where possible. Put PHI-holding services in their own cloud accounts or projects, with network rules that block traffic from non-PHI systems, and give each account its own encryption keys.

• Logs: Strip or mask patient fields before logs leave the service, and send audit events, which must contain identifiers, to the audit store rather than the general log platform.
• Analytics: Feed product analytics with event names and pseudonymous IDs, not names or clinical details.
• Error tracking: Scrub request bodies before error reports leave the service.
• Support tools: Give support staff a narrow view through the product, not database access.
• Test environments: Keep them outside the boundary by using synthetic data only.

Every system inside the boundary needs the full set of safeguards and, for vendors, a business associate agreement. Keeping the boundary small is the cheapest way to keep that list short.

Which calls should be synchronous and which asynchronous?

Make a call synchronous only when the user is waiting for its answer and the system on the other end is under your control. Anything that crosses to a partner, can be retried or can finish later belongs on a queue or event.

• Synchronous: Loading a chart, saving a note, checking a user's permissions and validating a form. The user needs an answer, and the services are yours.
• Asynchronous with a queue: Inbound HL7 v2 messages, outbound orders, claim submission and document indexing. They must not be lost, and a slow partner must not block the user.
• Asynchronous with events: Notifying other services that an appointment was booked or a result arrived, so each can react without the sender knowing about it.
• Synchronous with a fallback: Real-time eligibility checks and drug interaction checks from outside services. Call them live with a short timeout, and show a clear pending state if they do not answer.
• Scheduled batch: Bulk exports, analytics loads and reconciliation jobs that run outside care hours.

Every queue needs a dead-letter path and an alert. A message that fails silently in an interface queue is a lab result a clinician never sees.

How do you plan for failure and recovery?

Plan for failure in each layer and decide in advance what the product does when a part is down. The HIPAA Security Rule's contingency plan standard at 45 CFR 164.308(a)(7) requires a data backup plan, a disaster recovery plan and an emergency mode operation plan, with testing of those plans an addressable specification.

Architecture turns those plans into behavior. For each dependency, write down what users see when it fails and build that state on purpose.

• Partner EHR down: Queue outbound messages and show a banner; do not block local charting.
• Identity provider down: Keep existing sessions valid for a short, documented period and have a break-glass path for urgent access.
• One domain service down: Other services keep working, and screens that need the failed service show a clear message instead of an error page.
• Region or account loss: Restore from backups held in a separate account and region, with infrastructure rebuilt from code.
• Data corruption: Point-in-time restore for databases, plus the audit store to show what changed and when.

Test the plan by switching dependencies off in a staging environment and restoring real backups into a clean account. A recovery path that has never run is a hope, not a plan.

Architecture decisions to record early

Write each of these as a short architecture decision record with the context, the options considered, the choice and its consequences. They are the decisions new engineers and security reviewers ask about first.

• Tenancy: Whether customers share databases, schemas or accounts, and how tenant separation is enforced and tested.
• Canonical data model: Whether the internal model follows FHIR resources, a custom model or both, and which side owns the truth.
• Identity: Which identity provider, how customer single sign-on is federated and how patient identity is matched across systems.
• Encryption: Encryption at rest and in transit for every store and connection. Under 45 CFR 164.312, encryption is an addressable specification, so the decision record is also where any alternative measure is documented.
• Audit: The event format, where audit records live, who can read them and how long they are kept.
• Interface ownership: Which team owns each partner adapter and how partner changes are scheduled and tested.
• Deployment unit: Which services deploy independently and which must release together.

Review the records when the product changes direction, such as a move from one customer to many or a new class of partner. Decisions that no longer fit should be replaced with a new record, not quietly ignored.

How Agnotic can help

Most of the risk in a health product sits at the joins between layers: the adapters, queues, identity paths and data boundaries. Agnotic Technologies designs and builds those joins for the client, including the integration layer for HL7 v2, FHIR and X12, the PHI boundary and audit store, and the recovery paths that keep clinics working when a partner system is down.

For a product already in production, Agnotic can review the current architecture against the seven layers and write the decision records that are missing.

Sources

• 45 CFR 164.308: HIPAA administrative safeguards, including (a)(7) contingency plan
• 45 CFR 164.312: HIPAA Security Rule technical safeguards, including encryption specifications
• HL7 International: FHIR R4 specification