How to Build Template 4: Healthcare Patient Portal

How to Build Template 4: Healthcare Patient Portal

This template shows how to model a patient-facing healthcare portal at the System Context level. It highlights patient and staff actors, clinical systems of record, and compliance-sensitive integrations.

A healthcare portal is architecturally distinct from most consumer portals because it is not just a convenience layer. It is a regulated data access interface over clinical systems. Every design decision — authentication, data exchange, logging, messaging — is shaped by HIPAA requirements, interoperability standards like HL7 FHIR, and the risk profile of protected health information (PHI). This template makes those architectural forces visible from the first diagram.

What This Template Shows

• Patients and internal clinical staff using the same platform but through entirely different workflows
• The portal as a presentation and interaction layer that delegates to authoritative clinical systems rather than storing its own copies of clinical data
• HIPAA-sensitive dependencies including audit logging, secure messaging, and anonymized communications
• Regulated interoperability through HL7 FHIR for structured clinical data exchange
• Identity and access management through an enterprise directory, not a standalone user table

This is the right level when you need to communicate how the portal fits into the larger health system landscape — before any conversation about internal services or databases begins.

Embedded Diagram

Why This Context Diagram Works

The diagram makes four critical architectural signals visible in a single view:

The EHR is the system of record. The portal does not own clinical data. It reads from and writes back to the EHR. That means the portal is always a secondary system — the EHR is the authority on diagnoses, medications, lab results, and clinical notes. Architecture decisions must account for this dependency: the portal cannot function without EHR access, and any inconsistency between portal and EHR must always be resolved in the EHR's favor.

Data exchange is regulated. The connection between the portal and the EHR is not a simple database read. It goes through HL7 FHIR APIs, which impose a specific data model (FHIR Resources), specific authorization protocol (SMART on FHIR with OAuth 2.0), and specific audit requirements. Anyone reading the diagram understands immediately that this integration requires specialized knowledge and cannot be casually changed.

Patient and staff workflows are distinct. Patients access their own health records, request appointments, refill prescriptions, and message their care team. Clinicians access patient records for care delivery, document clinical encounters, respond to patient messages, and review incoming data. Schedulers manage the appointment calendar. IT administrators manage access controls and review audit logs. These are not the same workflows with different permissions — they have fundamentally different risk profiles, regulatory obligations, and performance requirements.

Compliance infrastructure is architectural, not operational. The Audit Logging Service is not a logging library inside the application. It is a separate system in the diagram because it is a non-negotiable architectural dependency. HIPAA requires that every access to PHI be logged with who accessed what, when, and why. That logging must be tamper-evident, retained for a minimum of six years, and available for compliance review. Treating this as a configuration detail rather than an architectural concern is how HIPAA violations happen.

Core Elements To Include

People

Patient The primary user of the portal. Patients access the portal to review their health records, see lab results, review visit summaries and clinical notes, request prescription refills, schedule or request appointments, pay bills, and communicate securely with their care team. The patient is typically authenticated via a consumer identity provider (email + password + MFA) with identity proofing requirements depending on the sensitivity of data shown. In the US, 21st Century Cures Act information blocking rules give patients the right to access their health data electronically, which makes the patient's data access flow a legal requirement, not just a product feature.

Clinician Physicians, nurse practitioners, physician assistants, and nurses who use the portal to respond to patient-initiated messages, review incoming data from patient devices, complete patient-facing documentation, and handle tasks that originate from the portal workflow. Clinicians authenticate via the enterprise directory with strong credential requirements. Their session context includes their licensure and care team assignments, which drive access control decisions.

Patient Coordinator / Scheduler Administrative staff who manage the appointment calendar, handle scheduling requests from patients, confirm appointments, and process pre-visit paperwork. Schedulers typically have read access to appointment-relevant patient data but not full clinical record access. Their workflow is heavily integrated with the Appointment Scheduling System and the EHR's scheduling module.

IT / Compliance Administrator Internal staff responsible for managing user provisioning, access controls, reviewing audit logs for suspicious activity, and managing the technical infrastructure of the portal. This actor is often invisible in product diagrams but is critical in a healthcare context because HIPAA requires a designated Privacy Officer role and regular access reviews. The IT administrator interacts with the Audit Logging Service and the identity provider directly.

Main System

Patient Healthcare Portal The central system being modeled. It is responsible for presenting clinical data sourced from the EHR, managing patient-initiated workflows (scheduling, messaging, refill requests), enforcing access control policies, and generating the audit trail required by HIPAA. The portal should be understood as an orchestration and presentation layer — it does not store clinical data independently from the systems of record it connects to.

External Systems

Epic EHR / Cerner The Electronic Health Record system is the clinical source of truth for the health system. It contains the longitudinal patient record: problem lists, medications, allergies, immunizations, lab results, radiology reports, clinical notes, visit history, and care plans. The portal reads from the EHR via the FHIR API to display clinical data to patients. It writes back to the EHR for actions like patient-reported health data, appointment confirmations, and message routing to clinical staff. Epic and Cerner are the two dominant EHR vendors in the US; the connection pattern is the same for both, though the specific FHIR implementation details and extension profiles may differ.

HL7 FHIR API The Fast Healthcare Interoperability Resources (FHIR) standard defines the data model and API specification for clinical data exchange. The FHIR API is the standardized interface layer between the portal and the EHR. FHIR Resources model clinical concepts — Patient, Observation, Condition, MedicationRequest, Appointment, DiagnosticReport — as structured JSON documents with defined schemas. The authorization protocol is SMART on FHIR, an OAuth 2.0 profile specifically designed for healthcare contexts, which handles both patient-facing (standalone launch) and clinician-facing (EHR launch) authentication flows. FHIR API is in the diagram as a distinct element because it represents a distinct integration surface with its own versioning, certification requirements (ONC certification in the US), and vendor-specific implementation guides.

Appointment Scheduling System Many health systems separate their scheduling system from their clinical EHR, particularly for complex multi-provider, multi-location scheduling. The scheduling system manages slot availability, resource constraints (rooms, equipment), provider calendars, and appointment lifecycle (requested, confirmed, checked in, completed, canceled, no-show). The portal integrates with this system for patient self-scheduling, appointment reminders, and waitlist management.

Pharmacy Management System Manages prescription fulfillment workflows. When a patient requests a prescription refill through the portal, the request is routed to the Pharmacy Management System, which handles dispensing status, insurance adjudication, controlled substance tracking, and pharmacy-to-patient communication. Tight integration here is important for medication adherence programs and for patient convenience, which is increasingly tied to patient satisfaction scores.

Azure Active Directory The enterprise identity provider for clinician and staff authentication. Staff identities are managed centrally — provisioned when staff join, deprovisioned immediately when they leave. Single sign-on allows clinical staff to access the portal within their existing EHR session context, reducing authentication friction and enabling EHR-launched portal workflows. Active Directory also provides role and group information that drives portal access control — which clinical staff can see which patients, based on care team membership and active encounters.

Secure Messaging Gateway Patient-to-clinician messaging in healthcare cannot go through standard email because email is not a sufficiently secure channel for PHI. The Secure Messaging Gateway enforces encryption, access controls, and audit trails on all patient-provider communications. It also handles the complexity of message routing within the health system — a message to "my doctor" needs to reach the right member of the care team, which may be a nurse triaging messages before they reach the physician.

SendGrid / Twilio Used for outbound notifications that do not contain PHI. Appointment reminders, portal login notifications, and message arrival alerts can be sent via email or SMS because they do not include the actual clinical content — they tell the patient "you have a new message in your portal" rather than including the message text. This distinction is architecturally important: the notification trigger contains no PHI, but the patient must authenticate to the portal to see the actual content. This is the standard HIPAA-compliant pattern for patient notifications.

Audit Logging Service / CloudWatch Every access to PHI — every page view, every data query, every export — must be logged with a minimum set of fields: user identity, timestamp, resource accessed, action taken, and the patient record affected. This service is the centralized, tamper-evident store for all such events. In AWS environments this is often built on CloudWatch Logs with log integrity features enabled; in more regulated environments it may be a purpose-built compliance logging platform. The audit logs must be retained for at least six years under HIPAA, must be available for compliance audits, and must support queries like "who accessed patient X's record in the last 30 days."

How FHIR Changes the Architecture

Understanding HL7 FHIR is essential to understanding why this architecture looks the way it does.

FHIR is not just a data format. It is a complete specification for clinical interoperability: REST API design, resource schemas, search parameters, terminology binding (ICD-10, SNOMED, LOINC codes), and security. The ONC (US Office of the National Coordinator for Health IT) requires EHR vendors to expose certified FHIR R4 APIs, which gives the portal a standardized way to query clinical data without custom EHR-vendor-specific integrations.

SMART on FHIR extends OAuth 2.0 with healthcare-specific scopes. A patient can grant the portal access to their own records (patient/*.read) without exposing other patients' data. A clinician can launch the portal from within the EHR context, carrying their authenticated identity and the current patient context (launch/patient), so they do not have to re-authenticate or re-search for the patient.

This combination — FHIR APIs plus SMART authorization — means the portal can be written against a standard interface rather than EHR-vendor-specific APIs, which reduces lock-in and makes it easier to support health systems using different EHR vendors.

HIPAA Compliance Architecture

HIPAA shapes the architecture in ways that are not optional:

Access controls must follow the minimum necessary standard — users should only be able to see the PHI required for their role and current purpose. This is not just a permission flag on a user record. It requires contextual access control driven by care team membership, active patient relationships, and encounter context.

Encryption is required for PHI at rest and in transit. All databases holding PHI must be encrypted. All API communications must use TLS. This is baseline — but it must be visible in infrastructure diagrams, not assumed.

Breach notification requires that any unauthorized access to PHI be detected, investigated, and reported to affected patients and HHS within defined timelines. This only works if the audit logging infrastructure is comprehensive enough to detect the breach in the first place.

Business Associate Agreements must be in place with every external system that handles PHI on behalf of the health system. This means SendGrid, Twilio, Stripe (if billing data includes PHI), and cloud providers all require BAAs. Selecting a vendor that will not sign a BAA (some consumer tools will not) makes that integration HIPAA non-compliant regardless of technical controls.

How To Adapt It

If your environment uses different vendors, keep the same shape and swap the system names:

• Epic or Cerner for the EHR — the FHIR interface pattern is the same for both
• Okta or Azure AD for enterprise identity — both support SAML and OIDC for SSO
• A custom or regional scheduling platform instead of a commercial product
• A purpose-built secure messaging platform if you need higher compliance assurance than commercial options

If your portal primarily reads data rather than writing back, reduce the wording on write operations and emphasize read-only access. A patient record viewer has a much simpler integration footprint than a full bidirectional portal.

If your health system is large enough to have a separate Patient Relationship Management system (like Salesforce Health Cloud), add it as an additional external system receiving events from the portal — appointment completions, care gap flags, patient preferences.

When To Use This Template

Use this template when you need to explain:

• how the patient portal relates to the EHR and why the EHR is the system of record, not the portal
• where HIPAA-sensitive data flows live and why they require specific architectural treatment
• why audit logging is a first-class architectural component, not an operational concern
• how SMART on FHIR and HL7 FHIR change the integration pattern compared to non-regulated systems
• why separate identity providers for patients and staff are not redundancy but a regulatory and security requirement
• how regulated interoperability shapes system boundaries in ways that consumer products do not face