Scheduling Service — Domain Model

Status: populated Owner: TBD Last updated: 2026-04-17 Companion: Service Template · 03 platform-services · 02 DDD

1. Aggregates

Root aggregate for a single patient appointment.

Invariants

#	Invariant
I-APT-01	Status transitions must follow the allowed graph (no backward transitions, no arbitrary jumps).
I-APT-02	A `booked` appointment holds an exclusive reference to a `Slot`; that slot is marked `busy`.
I-APT-03	Double-booking is rejected unless `allowDoubleBooking=true` is supplied by an authorized role.
I-APT-04	Cancelled appointment releases slot back to `free`.
I-APT-05	`patientId` references a patient in the same tenant (validated against registration-service events).
I-APT-06	Optimistic lock `version` required on status updates, cancellation, and reschedule.

FHIR Status State Machine

Governs resource availability windows for a provider, room, or piece of equipment.

Invariants

#	Invariant
I-SCH-01	A schedule belongs to exactly one `actor` (provider, location, or device) per tenant.
I-SCH-02	Schedule exceptions (blocked windows) override the base availability pattern.
I-SCH-03	`timezone` must be a valid IANA timezone string.

A bookable time window within a Schedule.

Invariants

#	Invariant
I-SLT-01	`status` is one of `free`, `busy`, `blocked`, `entered-in-error`.
I-SLT-02	A slot becomes `busy` atomically when an appointment is confirmed to it.
I-SLT-03	A slot cannot overlap with another slot of the same schedule in `free` or `busy` state.

Represents a patient's desire for an appointment type when no slot is available.

State Machine: waiting → fulfilled | deleted

Entity	Aggregate	Key attributes
`AppointmentActor`	Appointment	`actorType` (patient, practitioner, location, device), `actorId`, `required` flag
`AppointmentResponse`	Appointment	`actorId`, `participantStatus` (accepted/declined/tentative)
`ScheduleException`	Schedule	`start`, `end`, `reason`, `type` (holiday/maintenance)
`ScheduleAvailabilityPattern`	Schedule	`days[]` with `dow`, `start`, `end` (weekly template)

Value Object	Type
`AppointmentId`	`Branded<string, 'AppointmentId'>` — UUID
`ScheduleId`	`Branded<string, 'ScheduleId'>` — UUID
`SlotId`	`Branded<string, 'SlotId'>` — UUID
`AppointmentStatus`	`proposed`\|`pending`\|`booked`\|`arrived`\|`fulfilled`\|`cancelled`\|`noshow`\|`entered-in-error`
`SlotStatus`	`free`\|`busy`\|`blocked`\|`entered-in-error`
`AppointmentType`	Coded value (ROUTINE, WALKIN, EMERGENCY, etc.)
`ActorType`	`provider`\|`location`\|`device`
`WaitlistStatus`	`waiting`\|`fulfilled`\|`deleted`

NATS Subject	CloudEvents Type	Trigger	Version
`SCHEDULING.appointment.created`	`ghasi.scheduling.appointment.created`	Appointment booked or portal bridge creates proposed	v1
`SCHEDULING.appointment.updated`	`ghasi.scheduling.appointment.updated`	Status updated or rescheduled	v1
`SCHEDULING.appointment.cancelled`	`ghasi.scheduling.appointment.cancelled`	Appointment cancelled	v1
`SCHEDULING.appointment.noshow`	`ghasi.scheduling.appointment.noshow`	Status set to `noshow`	v1
`SCHEDULING.appointment.fulfilled`	`ghasi.scheduling.appointment.fulfilled`	Status set to `fulfilled`	v1
`SCHEDULING.checkin.completed`	`ghasi.scheduling.checkin.completed`	Status set to `arrived`	v1
`SCHEDULING.schedule.published`	`ghasi.scheduling.schedule.published`	Schedule created	v1
`SCHEDULING.slot.opened`	`ghasi.scheduling.slot.opened`	Slot created	v1
`SCHEDULING.waitlist.slot-available`	`ghasi.scheduling.waitlist.slot-available`	Cancellation frees a matching waitlist slot	v1
`SCHEDULING.appointment.reminder.sent`	`ghasi.scheduling.appointment.reminder.sent`	Reminder dispatched by async reminder service	v1

Term	Definition
Appointment	A planned patient visit to a provider/location at a specific time
Slot	A bookable time window within a schedule
Schedule	A recurring availability definition for a resource (provider, room, equipment)
Actor	A participant in an appointment (patient, provider, location, device)
Double-booking	Two appointments overlapping the same resource time window
No-show	Patient did not attend a booked appointment
Waitlist	Queue for patients awaiting an appointment type when no slot is currently available
Check-in	Recording that a patient has arrived (`arrived` status transition)
Reminder	Outbound notification sent to patient before appointment
Portal bridge	Pattern: patient-portal-service creates `proposed` appointment via NATS; staff confirms to `booked`
Availability pattern	Weekly template defining which time windows are open for a schedule
Schedule exception	A blocked window (holiday, maintenance) that overrides the availability pattern