# Phase: Healthcare Platform Foundation

| Field | Value |
| --- | --- |
| Identifier | `healthcare-13-0` |
| Status | Planned |
| Owner | Platform |
| Module(s) | `healthcare.*` foundation modules |
| Service(s) | `healthcare` |
| Depends On | Core entitlement; Identity (profile refs) |
| ADR(s) | TBD (Healthcare independent platform — to be accepted at implementation) |
| Manifest | [phase-manifest.yaml](../../ai-framework/phase-manifest.yaml) |
| Framework | [ADR-013](../../architecture/adr/ADR-013.md) · [ADR-018](../../architecture/adr/ADR-018.md) · [ADR-019](../../architecture/adr/ADR-019.md) |

## Objective

Establish an independent, tenant-aware Healthcare service scaffold with foundation aggregates, permissions, publish-only events, provider contracts, health/capabilities/metrics endpoints, and audit — without appointment, clinical workflow, pharmacy, or delivery engines.

## Enterprise Phase Discovery

> **Required before Implementation.**

| Field | Value |
| --- | --- |
| Discovery date | TBD at implementation |
| Inputs reviewed | [healthcare-roadmap.md](../../healthcare-roadmap.md) · [module-boundaries.md](../../architecture/module-boundaries.md) · [module-registry.md](../../module-registry.md#healthcare) · prior platform foundations (Delivery, Hospitality, Experience) |

### Baseline Inventory (exists today)

- Documentation registration (HC-Reg) complete
- No `backend/services/healthcare` runtime

### Target Responsibility (this phase when Complete)

- Independent service `healthcare` / `healthcare_db` (port 8010)
- Foundation aggregates and CRUD/list APIs with tenant isolation
- Permissions `healthcare.*`; transactional outbox events
- Provider Protocol stubs (Communication, CRM, Loyalty, Accounting, Delivery, Storage, AI, Identity)
- Architecture, tenant, permission, migration, security, docs tests green

### Gap Analysis

| Capability | Status | Action |
| --- | --- | --- |
| Service scaffold | Missing | Implement at 13.0 |
| Foundation aggregates | Missing | Implement at 13.0 |
| Appointment engine | Future | Phase 13.1 |
| Doctor panel / clinic admin | Future | Phases 13.2–13.3 |
| Patient portal / EHR / pharmacy | Future | Phases 13.4–13.6 |
| Delivery integration | Future | Phase 13.7 |

### Promoted to Implementation Scope

- Clinic, Branch, Department shells
- Doctor and Patient profile shells (platform user refs only)
- Roles, permissions catalog, configuration, settings, audit, outbox
- Health, capabilities, metrics endpoints

### Explicitly Excluded (future phase or other service)

- Appointment booking, schedules, slots (13.1)
- Visit sessions, queues, doctor workflows (13.2)
- Clinic services catalog admin (13.3)
- Patient self-service portal (13.4)
- Medical record encounters (13.5)
- Pharmacy network (13.6)
- Delivery job dispatch (13.7)
- Identity user administration (Identity)
- Communication provider ownership (Communication)
- Accounting journal posting (Accounting)

### Boundary Confirmations

- [x] No future-phase pull-forward (documentation)
- [x] No service-boundary violation (documentation)
- [x] No duplication of Delivery / Communication / Accounting domains
- [x] CRUD-only delivery rejected for implementation phase

## Business Analysis

| Item | Detail |
| --- | --- |
| Actors | Platform admin, clinic admin (future), doctor (future), patient (future) |
| Business capabilities (in phase) | Register clinics/branches; doctor/patient profile shells; tenant config |
| Success metrics | Service boots; tenant-isolated foundation APIs; tests green |
| Non-goals | Clinical workflows, billing, pharmacy, logistics |

## Scope

### In Scope

- Service scaffold under `backend/services/healthcare`
- Database `healthcare_db`; Alembic `0001_initial`
- Foundation models, repositories, services, validators, permissions, events
- `/health`, `/capabilities`, `/metrics`, `/api/v1/*` foundation routes
- Compose + env wiring (port 8010)

### Modules

| Module | Change type | Notes |
| --- | --- | --- |
| `healthcare.clinics` | new | Clinic aggregate shell |
| `healthcare.branches` | new | Branch under clinic |
| `healthcare.departments` | new | Department shell |
| `healthcare.doctors` | new | Doctor profile shell |
| `healthcare.patients` | new | Patient profile shell |
| `healthcare.roles` | new | Healthcare roles |
| `healthcare.permissions_catalog` | new | Permission definitions |
| `healthcare.configuration` | new | Tenant configuration |
| `healthcare.settings` | new | Settings key-value |
| `healthcare.external_providers` | new | Provider registration shells |
| `healthcare.audit` | new | Audit log |

### Domain Model

| Aggregate | Entities | Invariants |
| --- | --- | --- |
| Clinic | Branch, Department | Tenant-scoped; soft delete where applicable |
| Doctor | — | Links to Identity user ref; no Identity ownership |
| Patient | — | Links to Identity user ref; privacy-aware |
| HealthcareConfiguration | Setting | Tenant-scoped keys |

### Permissions

| Permission | Description |
| --- | --- |
| `healthcare.clinics.view` | List/read clinics |
| `healthcare.clinics.manage` | Create/update/archive clinics |
| `healthcare.doctors.view` | List/read doctors |
| `healthcare.doctors.manage` | Manage doctor profiles |
| `healthcare.patients.view` | List/read patients |
| `healthcare.patients.manage` | Manage patient profiles |
| `healthcare.settings.manage` | Manage healthcare settings |

### Events

| Event | When |
| --- | --- |
| `healthcare.clinic.created` | Clinic created |
| `healthcare.clinic.updated` | Clinic updated |
| `healthcare.doctor.created` | Doctor profile created |
| `healthcare.patient.created` | Patient profile created |
| `healthcare.setting.updated` | Setting changed |

### APIs

| Method | Path | Permission | Notes |
| --- | --- | --- | --- |
| GET | `/health` | public/ops | Liveness |
| GET | `/capabilities` | authenticated | Phase/capability discovery |
| GET | `/metrics` | ops | Basic metrics |
| GET/POST/PATCH | `/api/v1/clinics` | `healthcare.clinics.*` | List with page/filter/sort/search |
| GET/POST/PATCH | `/api/v1/doctors` | `healthcare.doctors.*` | Doctor profiles |
| GET/POST/PATCH | `/api/v1/patients` | `healthcare.patients.*` | Patient profiles |
| GET/PATCH | `/api/v1/settings` | `healthcare.settings.*` | Settings |

### Providers

| Interface | Owning service | Notes |
| --- | --- | --- |
| CommunicationProvider | Communication | Contracts only |
| DeliveryProvider | Delivery | Contracts only |
| StorageProvider | File Storage | Document refs |
| CRMProvider | CRM | Optional contact sync |
| AccountingProvider | Accounting | Future billing intents |

## Out of Scope

- Appointment engine (13.1)
- Doctor panel workflows (13.2)
- Clinic management catalog (13.3)
- Patient portal (13.4)
- Medical records (13.5)
- Pharmacy network (13.6)
- Delivery integration (13.7)
- Frontend UI

## Completion Criteria

- [ ] Objective met
- [ ] Enterprise Phase Discovery Record complete at implementation
- [ ] Definition of Done satisfied
- [ ] Tests green
- [ ] Handover completed
- [ ] Module registry version `0.13.0.0`

## Architecture Impact

- New independent service and database per database-per-service rule ([ADR-001](../../architecture/adr/ADR-001.md))
- Module boundaries updated at implementation

## Database Impact

- New `healthcare_db`; migration `0001_initial`

## Risks

- Premature clinical feature pull-forward from later phases
- Confusion with Sports Center `medical_information` shells — Healthcare owns clinical domain

## Related Documents

- [Healthcare Roadmap](../../healthcare-roadmap.md)
- [Phase area README](README.md)
- [Module Registry](../../module-registry.md#healthcare)
- [Module Boundaries](../../architecture/module-boundaries.md)
- [Progress](../../progress.md)
- [Next Steps](../../next-steps.md)