Patient Portal Service — Service Overview
Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 03 platform-services · 02 DDD
Purpose
The patient-portal-service is the Backend-for-Frontend (BFF) for all patient-facing digital channels. It surfaces a controlled, policy-filtered view of the patient's longitudinal health record and enables self-service actions — appointment requests, demographic updates, secure messaging entry, and results viewing. It serves both the responsive web portal and the React Native mobile app from a single API contract.
It is an optional licensed add-on (ehr.portal). Unlicensed tenants receive 403 MODULE_NOT_LICENSED.
Bounded Context Responsibilities
| In scope | Out of scope |
|---|---|
| Patient authentication session management (OIDC/OAuth2 + MFA) | Clinical data storage (owned by source-of-record services) |
| Policy-filtered FHIR read projections (Patient, AllergyIntolerance, MedicationRequest, Observation, Immunization, Appointment, DiagnosticReport, DocumentReference) | Claims adjudication and billing workflow (claims-service) |
| Appointment request submission to scheduling-service | Secure messaging storage (messaging-service) |
| Demographic update request workflow | PCI-scoped payment processing |
| Proxy / caregiver delegation management | Virtual visit session management (virtual-care-service) |
| Patient portal access audit log | Population health analytics |
| Patient-initiated FHIR Bundle export | |
| EOB / coverage read projections from claims-service | |
| AI-assisted navigation (non-diagnostic, Tier A only, via ai-gateway-service) | |
| Push notification dispatch (mobile) | |
| Account deletion / closure request routing |
Upstream Dependencies
| Service | Why |
|---|---|
| identity-service | JWT issuance, OIDC/OAuth2, MFA, patient realm |
| registration-service | Patient demographic data (Patient FHIR resource) |
| scheduling-service | Appointment reads and booking request intake |
| orders-service / ehr-service | MedicationRequest, medication summaries |
| laboratory-service | Observation results (policy-released only) |
| radiology-service | DiagnosticReport results (policy-released only) |
| claims-service | ExplanationOfBenefit, Coverage read projections |
| immunization-service | Immunization records |
| messaging-service | Secure message thread access (if licensed) |
| ai-gateway-service | Patient-facing AI (Tier A only, non-diagnostic) |
| audit-service | Portal access event pipeline |
Downstream Dependents
| Service | Dependency |
|---|---|
| (None) | patient-portal-service is a leaf BFF; no services depend on it |
Key Architectural Decisions
- BFF pattern. The portal service acts as a dedicated backend-for-frontend aggregating data from multiple upstream services. No raw inter-service calls are made from the browser or mobile app.
- FHIR R4 constrained read surface. Patient-facing data is expressed as FHIR R4 resources. Policy filters and result-release rules are applied server-side; the client never receives unreleased or restricted data.
- SMART on FHIR authorization model. Patient OAuth2 scopes are mapped to FHIR resource types (
patient/Patient.read,patient/Observation.read, etc.). Scope-to-resource enforcement is at the BFF layer. - Shared API contract for web and mobile. Both channels consume the same
/v1/portal/*REST surface and the same FHIR endpoints. Client-specific behavior is presentation-only. - No PHI in push notification payloads. Mobile push payloads contain only a notification type and deep link; the app fetches actual content after authentication.
- Proxy/caregiver delegation. ProxyDelegation records are scoped, audited, and enforced at the BFF boundary. A proxy cannot exceed the granted scope.
Architecture Diagram
Slice Involvement
| Slice | Role |
|---|---|
| S4 — Patient engagement | Core responsibility |
| S1 — Clinical workflow | Portal surfaces clinical read projections |
| S2 — Revenue cycle | EOB and coverage view from claims-service |
Source Reconciliation
Source: _sources/patient-portal/ (PAT-PORTAL v1.1). This is a new service; no legacy module merge required. FRs FR-PORT-001..013 map directly to FR-PORTAL-001..013. AI guidance requirements from FR-AI-007 apply to patient-facing AI Tier A access.