# Phase: Appointment Engine

| Field | Value |
| --- | --- |
| Identifier | `healthcare-13-1` |
| Status | Planned |
| Owner | Platform |
| Module(s) | `healthcare.appointments`, `healthcare.schedules`, `healthcare.availability` |
| Service(s) | `healthcare` |
| Depends On | `healthcare-13-0` (clinics, doctors, patients) |
| 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-018.md) · [ADR-019](../../architecture/adr/ADR-019.md) |

## Objective

Deliver a tenant-aware appointment scheduling engine: doctor/clinic availability, bookable slots, appointment lifecycle (book, confirm, cancel, reschedule, no-show), waiting list shells, and reminder intents via Communication contracts — without doctor panel UX, patient portal, or clinical record content.

## Enterprise Phase Discovery

> **Required before Implementation.**

| Field | Value |
| --- | --- |
| Discovery date | TBD at implementation |
| Inputs reviewed | Phase 13.0 handover · [healthcare-roadmap.md](../../healthcare-roadmap.md) · Communication contracts |

### Baseline Inventory (exists today)

- Phase 13.0 foundation (when complete): clinics, doctors, patients

### Target Responsibility (this phase when Complete)

- Schedule and availability management per doctor/clinic/department
- Appointment types and appointment aggregate with lifecycle transitions
- Slot generation and conflict detection
- Waiting list entry shells
- Events `healthcare.appointment.*`, `healthcare.schedule.*`
- Reminder dispatch via Communication provider (no provider ownership)

### Explicitly Excluded

- Doctor panel queue UX (13.2)
- Clinic services catalog admin (13.3)
- Patient self-service booking UI (13.4 — API may expose book for portal later)
- Visit notes / diagnoses (13.5)
- Pharmacy orders (13.6)
- Delivery jobs (13.7)

### Boundary Confirmations

- [x] No Communication template/provider ownership
- [x] No CRM opportunity or Loyalty point mutation
- [x] No Experience appointment page engine ownership

## Business Analysis

| Item | Detail |
| --- | --- |
| Actors | Clinic scheduler, doctor (indirect), patient (indirect) |
| Business capabilities | Define availability; book/reschedule/cancel; waitlist; reminders |
| Success metrics | Conflict-free booking; idempotent lifecycle; tenant isolation |
| Non-goals | Telemedicine video, payment at booking, insurance eligibility |

## Scope

### In Scope

- Aggregates: Schedule, AvailabilityWindow, AppointmentType, Appointment, WaitingListEntry
- Lifecycle: draft → confirmed → checked_in → completed / cancelled / no_show
- Commands: book, confirm, cancel, reschedule, mark_no_show
- List APIs with filter/sort/search by doctor, clinic, date range, status
- Permissions `healthcare.appointments.*`, `healthcare.schedules.*`
- Alembic `0002_phase_131_appointments`; version `0.13.1.0`

### Modules

| Module | Change type | Notes |
| --- | --- | --- |
| `healthcare.schedules` | new | Recurring/one-off schedules |
| `healthcare.availability` | new | Availability windows |
| `healthcare.appointment_types` | new | Visit type catalog |
| `healthcare.appointments` | new | Appointment engine |
| `healthcare.waiting_list` | new | Waitlist shells |

### Events

| Event | When |
| --- | --- |
| `healthcare.appointment.booked` | Appointment created |
| `healthcare.appointment.confirmed` | Confirmed |
| `healthcare.appointment.cancelled` | Cancelled |
| `healthcare.appointment.rescheduled` | Rescheduled |
| `healthcare.appointment.no_show` | Marked no-show |
| `healthcare.appointment.reminder_scheduled` | Reminder intent emitted |

## Out of Scope

- Doctor panel daily queue (13.2)
- Clinic admin staff roster (13.3)
- Patient portal routes (13.4)
- Medical record encounters (13.5)
- Pharmacy fulfillment (13.6)
- Delivery dispatch (13.7)

## Completion Criteria

- [ ] Appointment lifecycle APIs + tests green
- [ ] Conflict detection on overlapping slots
- [ ] Communication reminder contract invoked (mock in tests)
- [ ] Handover + registry at `0.13.1.0`

## Related Documents

- [Phase 13.0](phase-13-0-healthcare-foundation.md)
- [Healthcare Roadmap](../../healthcare-roadmap.md)
- [Module Registry](../../module-registry.md#healthcare)