Patient Portal Design Pack

Most engineering teams approach a patient portal like a standard SaaS dashboard. You scaffold a login, build a data grid, and throw up a profile page. Then you hit the wall. Healthcare data isn't just JSON; it's a constrained vocabulary with strict cardinality rules, and the regulatory overhead is brutal. If you miss a mustSupport flag in your FHIR StructureDefinition, the patient's record is incomplete. Worse, the ONC Cures Act Final Rule ^[1] mandates that patients have immediate, unrestricted access to their data. If your portal lags, hides data, or lacks machine-readable export options, you aren't just failing UX—you're violating federal interoperability mandates.

We built this skill pack so you don't have to reverse-engineer the Cures Act or guess at FHIR profiling. We've seen teams waste weeks building CRUD apps that fail audit because they treated clinical data like generic user data. You need a unified workflow that bridges clinical standards with modern web development. If you're also handling video visits, check out the Telemedicine UX Pack to ensure your portal's data layer aligns with telehealth workflows.

The Hidden Costs of Hand-Rolling Healthcare APIs

Ignoring the regulatory depth of a patient portal costs real money, reputation, and engineering hours. The 21st Century Cures Act imposes strict interoperability requirements that go beyond simple API endpoints. If your system blocks data export or delays patient access, you risk being flagged for information blocking ^[4]. This isn't a theoretical risk; ONC is actively enforcing these rules, and penalties can escalate quickly.

Beyond compliance, the security burden is heavy. Handling ePHI requires strict adherence to the HIPAA Security Rule, which NIST SP 800-66 Rev. 2 breaks down into administrative, physical, and technical safeguards ^[5]. If your portal's API lacks proper authentication scopes, encryption in transit, or audit logging, you're exposing sensitive health data. A single breach can trigger fines, loss of certification, and eroded patient trust.

We've seen teams spend weeks refactoring their backend because they didn't validate their FHIR profiles against required search parameters. The 21st Century Cures Act Final Rule requires certified EHRs to export a patient's full set of data ^[2]. If your portal doesn't support this, you're building a liability. Integrating a HIPAA Compliance Pack early can save you from these downstream headaches, but you still need a solid design foundation for the portal itself. For teams managing patient outreach, the Patient Engagement Pack offers strategies to keep users active once they're logged in.

A Regional Network's Three-Week Rollback

Imagine a team at a regional health network launching a new patient portal. They use a popular open-source framework and scaffold a dashboard in a weekend. The UI looks clean, and the dev team is proud. They connect it to their EHR using a generic REST adapter. Two weeks after launch, patient support tickets flood in. Users can't download their lab results in a machine-readable format. The API returns data, but it's missing critical fields because the team didn't constrain the FHIR Patient resource correctly. They didn't define the mustSupport flags for fields like birthDate or generalPractitioner.

When they dig into the logs, they find the SMART-on-FHIR authorization flow is misconfigured; the launch context is failing because the CapabilityStatement doesn't list the required resources. They realize they've violated the interoperability conditions of the Cures Act ^[3]. Now they have to halt the launch, rewrite the API spec, update the FHIR profiles, and re-test everything. This is a classic case of treating a regulated product like a hobby project. If you're building for sensitive populations, like mental health, you might also want to review the Mental Health Platform Pack to understand the specific data handling constraints in that domain.

What Changes Once the Pack Is Installed

Once you install the Patient Portal Design Pack, you shift from guessing to executing a proven workflow. You get a structured approach that starts with regulatory requirements, moves through UX design, and lands on technical implementation. The pack includes production-grade FHIR templates that enforce the correct StructureDefinitions for the Patient resource. You'll have an OpenAPI 3.1 spec that integrates FHIR endpoints with SMART auth flows, so you don't have to manually write security headers.

The included Spectral ruleset catches healthcare-specific violations before they hit CI. You'll validate your portal against structural integrity checks using our shell scripts. Errors are caught early, and your API is compliant with FHIR R5 standards out of the box. This isn't just a set of files; it's a workflow that ensures your portal is interoperable, secure, and accessible. For teams building internal tools, you can also look at the Developer Portal Pack to see how we handle API documentation and auth for developers, which shares some underlying patterns with patient-facing portals. If you're expanding into government services, the Citizen Services Portal Pack provides similar patterns for OIDC and legacy integration.

What's in the Patient Portal Design Pack

This pack is a multi-file deliverable designed for agent execution and CI/CD integration. Every file serves a specific purpose in the workflow.

• skill.md — Orchestrates the Patient Portal Design workflow, defines regulatory and UX phases, and explicitly references all templates, references, scripts, validators, and tests for agent execution.
• templates/fhir-patient-profile.json — Production-grade FHIR StructureDefinition constraining the Patient resource for portal-specific data capture, ensuring mustSupport flags and derivation rules.
• templates/fhir-server-capability.yaml — FHIR CapabilityStatement defining the portal's REST API endpoints, supported resources (Patient, Observation), and SMART-on-FHIR security configuration.
• templates/openapi-portal-api.yaml — OpenAPI 3.1 specification for the patient portal backend, integrating FHIR endpoints, SMART auth flows, and compliance headers.
• references/healthcare-compliance.md — Canonical knowledge on HIPAA Security Rule, WCAG 2.1 AA accessibility, SMART-on-FHIR OAuth 2.0, and FHIR R5 security framework excerpts.
• references/fhir-interoperability-guide.md — Embedded FHIR R5 specification overview, REST API operations, search parameters, and profiling concepts from authoritative sources.
• scripts/validate-portal.sh — Executable validator that checks structural integrity of OpenAPI and FHIR templates, exits non-zero on missing required fields or syntax errors.
• validators/openapi-spectral.yaml — Spectral ruleset enforcing healthcare-specific OpenAPI best practices, security headers, and FHIR-aware endpoint naming.
• tests/test-portal-validator.sh — Test harness that executes the validation script, asserts exit code 0, and reports pass/fail status for CI/CD integration.

Install and Ship

Stop guessing at FHIR profiles and start shipping compliant patient portals. Upgrade to Pro to install the Patient Portal Design Pack and get the structured workflow your team needs to pass audits and delight patients.