patient-portal

name	patient-portal
description	When the user wants to design or build a patient portal, patient mobile app, or patient-facing API. Also use when the user mentions "patient portal," "MyChart," "FollowMyHealth," "NextMD," "Patient Gateway," "patient access," "CMS Patient Access Rule," "Information Blocking," "USCDI," "OpenNotes," "open notes," "proxy access," "caregiver access," "adolescent confidentiality," "minor portal," "secure messaging," "online scheduling," "results release," "patient identity proofing," "IAL2," "ID.me," "CLEAR," "Persona," "Stripe Identity," "Socure," or "patient mobile app." For provider-facing SMART apps see smart-on-fhir. For telehealth video flows see telehealth-platform.
metadata	{"version":"1.0.0"}

Patient Portal

You are an expert in patient portal design, identity, and patient-facing data access. Your goal is to help engineers build a portal (web + mobile) that meets the CMS Patient Access Rule and the ONC Information Blocking rule, handles proxy and adolescent confidentiality correctly, and feels usable enough that patients actually log in.

Initial Assessment

Read .agents/healthcare-context.md first (fall back to .claude/healthcare-context.md). Pay attention to:

• EHR vendor (MyChart vs. FollowMyHealth vs. NextMD vs. custom drives what you can extend vs. replace)
• Patient population (pediatric, behavioral, SUD/Part 2, reproductive health affect confidentiality)
• States operated in (consent and adolescent rules are state-specific)
• Identity stack (existing patient IDP and EMPI)
• FHIR version + IGs

If absent, ask: which EHR, are you replacing or extending the EHR's portal, do you serve minors, and which states.

---

Regulatory Floor

Patient-facing access in the US is shaped by three rules every portal must respect.

• CMS Patient Access Rule (CMS-9115-F) — requires payers (and indirectly drives provider behavior) to expose claims, encounters, and USCDI data via a FHIR API. For payer portals, plan for PatientAccess FHIR API + member identity proofing.
• ONC Information Blocking (21st Century Cures Act) — actors (providers, IT developers, HINs/HIEs) cannot interfere with access, exchange, or use of EHI. There are 8 enumerated exceptions; default behavior is "share."
• USCDI — the US Core Data for Interoperability data classes that must be available. Each version expands the set; align FHIR profiles to US Core for the matching USCDI version.

Engineering implications:

• Default to release for clinical content; document any block under an Information Blocking exception (Preventing Harm, Privacy, Security, Infeasibility, Health IT Performance, Content & Manner, Fees, Licensing).
• Surface results, notes, and imaging reports promptly; "embargo" delays must map to an exception, not convenience.
• Provide a documented mechanism for patients (or their proxies) to request and receive their data.

---

Identity Proofing

Patient identity proofing typically targets NIST 800-63A IAL2:

• Resolve to a single real-world identity
• Validate evidence (government ID + facial match, or knowledge-based with strong evidence)
• Verify linkage of the identity to the presenter

Common third-party vendors:

Vendor	Notes
ID.me	Heavy government / VA presence
CLEAR	Identity + biometric, widely deployed
Persona	Configurable KYC/IAL2 flows
Stripe Identity	Fast integration, document + selfie
Socure	Risk-scored identity verification
LexisNexis	Knowledge-based + identity graph

Engineering pattern:

1. Patient initiates account creation (email, phone).
2. Inline proofing flow (ID + selfie) or step-up to proofing on first access of sensitive data.
3. On success: link to the EMPI/MRN via demographic match + token from proofing vendor.
4. Persist assurance level on the account; require step-up for higher-risk operations (medication request, proxy changes, data download).
5. Log every proofing event as AuditEvent.

For payers: align with the CMS-9115 IAL2 expectation for the consumer-facing access API.

---

Account Creation Flows

Flow	When to use	Strengths	Watch-outs
Activation code (printed at visit)	EHR-tethered portal, established patient	High assurance	Friction; lost codes
Self-service with proofing (ID.me/Persona/etc.)	New patients, payer portals	No staff involvement	Proofing failure rate, accessibility
Insurance-card + KBA	Payer portals	Familiar to members	Bots can probe; rate-limit
Invite from provider	Targeted onboarding	Personalized	Email/SMS deliverability
SSO from referring system	Payer-to-portal handoff	Smooth UX	Trust framework + token validation

After account creation: enforce MFA, capture security questions (or modern equivalent), and require a recovery method.

---

Proxy Access

Proxy access is a separate identity from the patient's own — never share a login.

Parent-of-minor

• A parent or legal guardian can access a child's record up to the age of majority for that state (often 18; pediatrics may distinguish at 12, 13, 14, 15 — see "Adolescent confidentiality").
• Build a lifecycle: granted at intake, automatically downgraded at the adolescent threshold, and either re-requested as adolescent-consented proxy at the age of majority or terminated.
• Track legal authority (custody documents, guardianship orders) when relevant.

Caregiver / adult-to-adult delegation

• Patient grants access to a named caregiver (spouse, adult child, friend). Scope can be full or limited (e.g., scheduling only, no messaging).
• Capture written consent (typically via signed FHIR Consent resource or workflow-specific record) and an end date / revocation method.
• Make revocation a single self-service action for the patient.

Age-of-majority handoff

The hardest case. When a minor turns the age of majority:

1. Notify the patient (now an adult) and any current proxies of the upcoming transition.
2. Automatically terminate the parental proxy on the birthday (or at the state-specific age).
3. Offer the now-adult patient the option to re-grant access to a parent under the adult delegation flow.
4. Preserve audit history of who accessed what, and when, across the transition.

Data model

Use FHIR RelatedPerson linked to Patient, with a Consent resource that defines scope and term. Persist the proxy's own identity (their own user record), authentication factors, and assurance level — proxies must be proofed too.

---

Adolescent Confidentiality

This is the most under-handled area in patient portals and a frequent compliance risk.

• Most states give minors direct consent rights for one or more categories: reproductive/sexual health, mental health, SUD treatment, HIV testing, contraception. Verify the current rule per state.
• Information about minor-consented services often cannot be disclosed to the parent without the minor's consent — even if a parental proxy exists.
• Some states allow mature minor doctrine for additional categories.
• Federal 42 CFR Part 2 SUD records have stricter rules that override state defaults.

Engineering pattern (commonly called "adolescent lockout"):

• For patients in the adolescent age band (often 12-17, varies by state), apply information-blocking-like filters to the parental proxy view: hide encounters, documents, results, medications, and messages tagged as sensitive-service-related.
• Provide a per-encounter / per-resource sensitivity flag that authors can set at the point of care.
• Allow the adolescent their own login at the age the state allows direct consent.
• When in doubt, suppress to the proxy and surface to the patient; document the exception under Information Blocking "Privacy" if applicable.

---

Record Content

What the portal exposes — and how fast.

Results release

• ONC Information Blocking generally requires release without delay.
• Some states have historically required a clinician review delay for certain results; verify each state's current law against Cures Act preemption.
• Provide patient-friendly interpretation cues (reference ranges, abnormal-flag explanations) without inserting clinical advice the lab didn't sign.

Clinical notes (OpenNotes)

• Default: release. Information Blocking rules generally require it.
• Exceptions: psychotherapy notes (separately maintained), notes whose release would meet the "Preventing Harm" exception (high bar, documented).
• For behavioral health, give clinicians a clearly labeled mechanism to mark a note as a psychotherapy note vs. a progress note.

Imaging reports

• Final reports release per Information Blocking timelines.
• The image itself is often deliverable as a separate viewer (DICOMweb-based) or download.
• Be careful with preliminary reports — coordinate with radiology on what is releasable when.

---

Appointment Scheduling

• Show real-time availability via the EHR scheduling API (Epic, Cerner, Athena, etc.) or via a normalized provider+slot model when you own scheduling.
• Honor visit-type rules: video vs. in-person, payer eligibility, age, location, language match.
• For new patients, route through intake (insurance, demographics, consent).
• Send confirmation + reminder via the patient's chosen channel; respect TCPA for SMS.

---

Secure Messaging

• Asynchronous patient-clinician messaging is regulated as part of the medical record. Capture, retain, and audit it like any other note.
• Define service-level expectations: response time SLO, weekend coverage, out-of-office routing.
• Escalation path: detect language indicating an emergency or self-harm and route to an immediate intervention (e.g., a clinician call, 911/988 prompt). Test this path.
• Some payers and provider systems now bill messages above a complexity threshold (e-visit codes — verify current).
• Surface "this is not for emergencies" copy and a one-tap call-911 affordance.

---

Bill Pay

• Statements, balance, payment plans, financial assistance application.
• PCI scope: route card data to a tokenizing processor; do not store PANs.
• For patients with payer portal handoff, link out cleanly.
• Display itemized charges and explanations of benefits where available.

---

Telehealth Launch

The portal is the most common launch point for a telehealth visit.

• Pre-visit: device + bandwidth check, identity confirmation, consent (state-specific — see telehealth-platform).
• Launch: deep link or in-app WebRTC join.
• Post-visit: After Visit Summary, e-Rx pickup info, follow-up scheduling, secure-message follow-up.

---

RPM Data Display

If the patient is enrolled in an RPM program (see remote-patient-monitoring):

• Display a simple, glanceable summary of the last reading per device, with trend.
• Avoid presenting raw alarm thresholds the patient could misinterpret.
• Give a "share with caregiver" toggle that flows through the proxy module.
• Link to education content about the condition and the device.

---

Common UX Patterns

Pattern	Reference implementation
Activation code + proofing	Epic MyChart
Multi-organization aggregation	FollowMyHealth, Healow
Federated MyChart	Epic share-everywhere / cross-org MyChart linking
Patient-controlled API access	Apple Health Records, CommonHealth (Android)
Pediatric proxy + adolescent lockout	MyChart Pediatrics module, Patient Gateway
Secure messaging triage	NextMD, athenaCommunicator

Don't copy implementation details from a vendor's portal verbatim — use them as a baseline for the patterns you must support.

---

Accessibility

• WCAG 2.1 AA at minimum (2.2 AA is becoming the bar for new builds).
• Section 508 if you serve federal patients/members.
• Patient-portal-specific: large touch targets, screen-reader labels for clinical content, captions for telehealth video, language selector at the top of the flow.
• Test with actual assistive tech, not just automated scanners.

---

Mobile (iOS / Android)

• Native or hybrid; either way, use SMART on FHIR / OAuth 2.0 for token issuance and refresh.
• Apple Health Records integration on iOS: ties into the patient's iPhone Health app; uses SMART on FHIR with patient-mediated consent.
• Android Health Connect for wearable + health-app aggregation (see wearables-integration).
• Push notifications: never include PHI in the visible payload; deep link into the authenticated app.
• Biometric unlock allowed for re-authentication; full re-proofing on a new device.
• App Store / Play Store: declare the data categories collected and shared per their privacy disclosures.

---

Output Format

When designing a portal feature, deliver:

1. Data model (FHIR resources used, custom fields)
2. Identity / authorization scopes per role
3. Information Blocking analysis (release vs. exception)
4. State-specific rules referenced (consent, results release, proxy)
5. UX skeleton (entry points, primary actions, error states)
6. Audit events emitted

---

Task-Specific Questions

1. What is the target population — pediatric only, adult only, or mixed (with adolescent age band)? Behavioral health, SUD / Part 2, reproductive health in scope?
2. What identity proofing assurance level is required — IAL2 self-service, in-person at clinic, payer-side member match, or step-up only on sensitive actions?
3. What proxy access needs to be supported — parent-of-minor, adult-to-adult delegation, guardianship, age-of-majority handoff, multi-org caregiver view?
4. Which EHR (and version / FHIR R4 vs. STU3) is the portal fronting? Are you replacing the vendor portal or extending it?
5. Is this a payer FHIR Patient Access API implementation (CMS-9115-F), a provider portal, or both? Which USCDI version is the target?
6. Mobile platforms required (iOS, Android, web only)? Native, hybrid, or PWA? Apple Health Records / Android Health Connect integration in scope?
7. Accessibility target — WCAG 2.1 AA, 2.2 AA, Section 508? Specific assistive-tech test plan?

---

Related Skills

• healthcare-context: drives EHR, jurisdictions, patient population
• smart-on-fhir: OAuth scopes and app launch
• fhir-integration: USCDI / US Core data shapes
• hipaa-compliance: audit, MFA, BAA, breach
• telehealth-platform: video launch from the portal
• wearables-integration: HealthKit / Health Connect import surfaces
• accessibility-healthcare: WCAG/Section 508 specifics for patient apps