Patient Portal Service — Epics
Service: patient-portal-service Epic prefix: PORTAL-EPIC Last updated: 2026-04-18
Epics
PORTAL-EPIC-01 — Portal Account Lifecycle and Authentication
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Portal account registration, MFA, and account lifecycle management |
| Status | To Do |
| Priority | Must |
| Labels | service:patient-portal-service, domain:patient_portal, slice:S4 |
| Components | portal-account, authentication, keycloak-patient-realm |
| Fix version | M1 |
| FR references | FR-PORTAL-001, FR-PORTAL-009, FR-PORTAL-010 |
| Legacy FR refs | FR-PORT-001, FR-PORT-009 |
| Dependencies | identity-service IDENT-EPIC-01 |
| Rollup status | Not started |
Business outcome: Patients can securely register for and manage their portal accounts with MFA, enabling self-service access to their health records.
Description: This epic covers the end-to-end patient account lifecycle: registration (binding patient identity to a Keycloak subject), email/phone verification, MFA enrollment (mandatory TOTP), account suspension and reinstatement by admin, and patient-initiated account deletion. It also governs the OIDC/PKCE login flow and session management (15-min access token, 24-h refresh with rotation).
Stories: PORTAL-US-001, PORTAL-US-002, PORTAL-US-003, PORTAL-US-004
PORTAL-EPIC-02 — Health Record Read Surface (FHIR Projections)
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Patient-facing FHIR read projections across chart sections and clinical data |
| Status | To Do |
| Priority | Must |
| Labels | service:patient-portal-service, domain:patient_portal, slice:S4 |
| Components | chart-sections, fhir-bff, policy-filter |
| Fix version | M1 |
| FR references | FR-PORTAL-002, FR-PORTAL-007 |
| Legacy FR refs | FR-PORT-002, FR-PORT-007 |
| Dependencies | registration-service, laboratory-service, radiology-service, patient-chart-service, immunizations-service |
| Rollup status | Not started |
Business outcome: Patients have a clear, secure, policy-filtered view of their longitudinal health record across all relevant FHIR resource types.
Description: This epic delivers the BFF query surface for chart sections (allergies, medications, vitals, immunizations, problems, documents), lab results (with release policy enforcement), radiology results (with release policy enforcement), and patient summary. All data is sourced read-only from upstream services and projected through the BFF with SMART scopes enforced. Unreleased results are never surfaced to patients.
Stories: PORTAL-US-005, PORTAL-US-006, PORTAL-US-007
PORTAL-EPIC-03 — Appointment Request and Self-Scheduling
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Patient appointment request submission and appointment list view |
| Status | To Do |
| Priority | Must |
| Labels | service:patient-portal-service, domain:patient_portal, slice:S4 |
| Components | appointment-bff, scheduling-client |
| Fix version | M1 |
| FR references | FR-PORTAL-003 |
| Legacy FR refs | FR-PORT-003 |
| Dependencies | scheduling-service SCHED-EPIC-01 |
| Rollup status | Not started |
Business outcome: Patients can request appointments and view their upcoming/past appointments from the portal, reducing phone-based scheduling load.
Description:
Covers GET /v1/portal/appointments (list upcoming + past from scheduling-service) and POST /v1/portal/appointments/request (submit a booking request to scheduling-service). Also covers appointment cancellation. Slot contention is handled by scheduling-service; the portal records the request event and surfaces status to the patient.
Stories: PORTAL-US-008, PORTAL-US-009
PORTAL-EPIC-04 — Medication and Refill Requests
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Medication list view and prescription refill request workflow |
| Status | To Do |
| Priority | Must |
| Labels | service:patient-portal-service, domain:patient_portal, slice:S4 |
| Components | medication-bff, medication-client |
| Fix version | M1 |
| FR references | FR-PORTAL-004 |
| Legacy FR refs | FR-PORT-004 |
| Dependencies | medication-service MED-EPIC-01 |
| Rollup status | Not started |
Business outcome: Patients can view their active medications and request prescription refills without a phone call.
Description:
Medication list view surfaces MedicationRequest resources from medication-service with SMART scope patient/MedicationRequest.read. Refill request (POST /v1/portal/medications/{id}/refill) creates a pending request routed to the prescribing workflow. Refill request status is surfaced back to the patient via polling.
Stories: PORTAL-US-010, PORTAL-US-011
PORTAL-EPIC-05 — Proxy Delegation and Caregiver Access
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Scoped proxy/caregiver access granting and enforcement |
| Status | To Do |
| Priority | Must |
| Labels | service:patient-portal-service, domain:patient_portal, slice:S4 |
| Components | proxy-delegation, access-enforcement |
| Fix version | M2 |
| FR references | FR-PORTAL-006 |
| Legacy FR refs | FR-PORT-006 |
| Dependencies | PORTAL-EPIC-01 |
| Rollup status | Not started |
Business outcome: Parents, guardians, and authorized caregivers can securely access dependent patients' portal data within legally-scoped, auditable delegation grants.
Description:
Covers the full ProxyDelegation lifecycle: grant (scoped, time-limited), use (enforced server-side on every request), revoke (immediate). Delegation scope limits which FHIR resource types the proxy can view. All proxy accesses are separately audited with actingAsProxy=true. Proxy cannot exceed grantor's own permissions.
Stories: PORTAL-US-012, PORTAL-US-013
PORTAL-EPIC-06 — PHR Export and Data Portability
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Patient-initiated FHIR Bundle export for health record portability |
| Status | To Do |
| Priority | Should |
| Labels | service:patient-portal-service, domain:patient_portal, slice:S4 |
| Components | export-job, fhir-bundle-assembly |
| Fix version | M2 |
| FR references | FR-PORTAL-011 |
| Legacy FR refs | FR-PORT-011 |
| Dependencies | PORTAL-EPIC-02 |
| Rollup status | Not started |
Business outcome: Patients can download their full health record as a FHIR Bundle, satisfying GDPR right-to-portability and MoPH data-sharing requirements.
Description:
Async export job assembles FHIR resources from all upstream services into a application/fhir+ndjson bundle. Patient polls job status via GET /v1/portal/export/{jobId}/status; downloads from a time-limited, tenant-region-bound presigned URL. Export job is idempotent per patient per time window. Supports selective resource type inclusion.
Stories: PORTAL-US-014, PORTAL-US-015
PORTAL-EPIC-07 — AI Navigation Assistant
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Non-diagnostic portal navigation assistant powered by ai-gateway-service |
| Status | To Do |
| Priority | Could |
| Labels | service:patient-portal-service, domain:patient_portal, slice:S4 |
| Components | ai-navigation, ai-gateway-client |
| Fix version | M3 |
| FR references | FR-PORTAL-013 |
| Legacy FR refs | FR-AI-007 |
| Dependencies | ai-gateway-service AIGW-EPIC-01 |
| Rollup status | Not started |
Business outcome: Patients unfamiliar with the portal can navigate to the right section using natural language, reducing support burden and improving health engagement.
Description:
Tenant-opt-in feature (feature flag ai.patient-assistant). Routes patient queries through ai-gateway-service Tier A (non-diagnostic). System prompt restricts responses to navigation guidance only. PHI never included in prompts. Moderation filter blocks disallowed content. Rate-limited at 10 requests per session.
Stories: PORTAL-US-016, PORTAL-US-017
PORTAL-EPIC-08 — Billing and Coverage View
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Patient view of insurance coverage and explanation of benefits |
| Status | To Do |
| Priority | Should |
| Labels | service:patient-portal-service, domain:patient_portal, slice:S2 |
| Components | billing-bff, claims-client |
| Fix version | M2 |
| FR references | FR-PORTAL-008 |
| Legacy FR refs | FR-PORT-008 |
| Dependencies | claims-service CLAIMS-EPIC-01 |
| Rollup status | Not started |
Business outcome: Patients understand their insurance coverage and can review EOBs without contacting billing staff.
Description:
Read-only projections of Coverage and ExplanationOfBenefit FHIR resources from claims-service, filtered by the portal's SMART scopes. Cached with a longer TTL (120s) given infrequent update cadence.
Stories: PORTAL-US-018