Scheduling Service — Service Overview
Status: populated Owner: TBD Last updated: 2026-04-17 Companion: Service Template · 03 platform-services · 02 DDD
1. Purpose
The scheduling-service owns all appointment and resource availability management for the Ghasi national eHealth platform. It governs the full lifecycle of patient appointments — from slot creation and availability search through booking, check-in, no-show handling, waitlist management, and reminder dispatch.
It is a core baseline service. No clinic visit can be formally tracked without an appointment record.
2. Bounded Context
| Attribute | Value |
|---|---|
| Bounded context | scheduling |
| Module ID (legacy) | ADMIN-SCHED |
| DDD context type | Supporting domain |
| Bundle | Core EHR — always-on baseline |
| License key | ehr.scheduling |
| FHIR canonical resources | Appointment, AppointmentResponse, Schedule, Slot, HealthcareService |
3. Responsibilities
| In scope | Out of scope |
|---|---|
| Provider, room, and equipment schedules | Pharmacy dispensing workflows |
| Slot creation and availability management | Lab orders or results |
| Appointment booking, rescheduling, cancellation, no-show | Patient portal UI (owned by patient-portal-service) |
| Multi-resource appointment (provider + room + equipment) | Billing / claims |
| Conflict prevention and double-booking guard | Clinical documentation |
| Waitlist with priority and auto-fill from cancellations | Registration (owns patient identity) |
| Appointment reminder dispatch (async, via NATS) | Provider directory (owns Practitioner) |
| FHIR R4 Appointment/Schedule/Slot/HealthcareService surface | |
| HL7 v2 SIU inbound/outbound adapter | |
| Patient self-booking via portal bridge (portal-appointment.requested) | |
| Localized reminders (RTL templates, facility timezone) |
4. Upstream and Downstream Dependencies
5. Slice Involvement
| Slice | Involvement |
|---|---|
| S0 (core) | Owner — appointment CRUD, slots, schedules, events |
| S1 (clinical) | Participant — appointment context consumed by orders (referral) and chart |
| S2 (interop) | Participant — FHIR Appointment/Slot surface; HL7 SIU via interop |
| S3 (patient engagement) | Participant — self-booking from portal |
6. Key Architectural Decisions
| Decision | Rationale |
|---|---|
| FHIR Appointment status vocabulary canonical | proposed, pending, booked, arrived, fulfilled, cancelled, noshow, entered-in-error — legacy names retired |
| Conflict prevention at DB level | Unique partial index on (scheduleId, startAt) for free slots; booking atomically sets busy |
| Reminder dispatch is async (NATS) | Avoids request latency; retries on failure; downstream handles template rendering |
| Waitlist auto-fill on cancellation | Event-driven: appointment.cancelled triggers slot-available check |
| Portal bridge pattern | portal.appointment.requested creates a proposed appointment for staff to confirm — no direct portal write to booked |
| Tenant isolation via RLS | All tables scoped by tenant_id |
7. Architecture Diagram
8. Source Reconciliation
Single source module _sources/scheduling/. The patient portal appointment flow (SPEC.md §4.1) is documented as a bridge pattern — the scheduling-service owns the canonical appointment; the portal-service owns the request intake event. No module split required.