# Phase: Patient Portal

| Field | Value |
| --- | --- |
| Identifier | `healthcare-13-4` |
| Status | Planned |
| Owner | Platform |
| Module(s) | `healthcare.patient_portal`, `healthcare.patient_documents` |
| Service(s) | `healthcare` |
| Depends On | `healthcare-13-0`, `healthcare-13-1` |
| ADR(s) | TBD |
| Manifest | [phase-manifest.yaml](../../ai-framework/phase-manifest.yaml) |
| Framework | [ADR-013](../../architecture/adr/ADR-013.md) · [ADR-018](../../architecture/adr/ADR-019.md) · [ADR-019](../../architecture/adr/ADR-019.md) |

## Objective

Expose patient-facing self-service APIs: profile read/update (healthcare fields only), appointment list/book/cancel via appointment engine, document download refs, and notification preferences — without Identity admin, full medical record write path, or frontend UI in this phase.

## Enterprise Phase Discovery

> **Required before Implementation.**

| Field | Value |
| --- | --- |
| Discovery date | TBD at implementation |
| Inputs reviewed | Phase 13.1 appointment APIs · Identity profile refs · Communication preferences |

### Target Responsibility (this phase when Complete)

- Patient-scoped API surface (authenticated patient context)
- Profile extensions: emergency contact refs, preferred clinic, language
- Appointment self-service: list upcoming/past, book (policy-aware), cancel/reschedule
- PatientDocumentRef listing (Storage refs; upload via Storage contract)
- NotificationPreference shells → Communication client
- Permissions `healthcare.patient_portal.*`
- Events `healthcare.patient_portal.*`

### Explicitly Excluded

- Identity credential/password admin
- Loyalty campaigns and point earn
- Medical record clinical edits by patient (13.5 read-only subset may be exposed later)
- Pharmacy checkout (13.6)
- Delivery tracking UI (13.7)
- Experience public site (Experience service)

## Business Analysis

| Item | Detail |
| --- | --- |
| Actors | Patient (authenticated end user) |
| Business capabilities | Self-service appointments; view shared documents; manage comms prefs |
| Success metrics | Patient can only access own tenant-scoped data |
| Non-goals | Guest booking without auth, family proxy accounts (future) |

## Scope

### In Scope

- Aggregates: PatientPortalProfile (extends Patient), PatientDocumentRef, PatientNotificationPreference
- APIs under `/api/v1/patient-portal/*` or patient-scoped deps on existing routes
- Integration with appointment engine commands (no duplicate appointment logic)
- Alembic `0005_phase_134_patient_portal`; version `0.13.4.0`

### APIs (planned)

| Method | Path | Permission | Notes |
| --- | --- | --- | --- |
| GET | `/api/v1/patient-portal/me` | patient context | Profile |
| PATCH | `/api/v1/patient-portal/me` | patient context | Limited fields |
| GET | `/api/v1/patient-portal/appointments` | patient context | Own appointments |
| POST | `/api/v1/patient-portal/appointments` | patient context | Book via engine |
| POST | `/api/v1/patient-portal/appointments/{id}/cancel` | patient context | Cancel |
| GET | `/api/v1/patient-portal/documents` | patient context | Storage refs |

## Out of Scope

- Doctor panel (13.2)
- Clinic admin (13.3)
- Full EHR write (13.5)
- Pharmacy (13.6)
- Delivery (13.7)
- Frontend patient app

## Completion Criteria

- [ ] Patient isolation tests (cannot read other patients)
- [ ] Appointment self-service flows green
- [ ] Handover + registry at `0.13.4.0`

## Related Documents

- [Phase 13.1](phase-13-1-appointment-engine.md)
- [Healthcare Roadmap](../../healthcare-roadmap.md)
- [Module Registry](../../module-registry.md#healthcare)