Scheduling

FK Relationship Diagram

erDiagram
    Provider ||--o{ Schedule : "owns"
    Location ||--o{ Schedule : "hosts"
    Schedule ||--o{ Slot : "contains"
    VisitType ||--o{ Slot : "typed by"
    Slot ||--o{ Appointment : "books into"
    Patient ||--o{ Appointment : "attends"
    Provider ||--o{ Appointment : "sees"
    VisitType ||--o{ Appointment : "typed by"
    EligibilityCheck ||--o| Appointment : "verifies"
    Appointment ||--o| Appointment : "rescheduled from"
    Location ||--o{ Resource : "houses"
    Provider ||--o| Resource : "linked to"
    User ||--o| Resource : "linked to"
    VisitType ||--o{ VisitStage : "broken into"
    Patient ||--o{ WaitlistEntry : "requests"
    VisitType ||--o{ WaitlistEntry : "for type"
    Provider ||--o| WaitlistEntry : "prefers"
    Slot ||--o| WaitlistEntry : "offered"
  

Resource-Graph Scheduling Model

The scheduling engine uses a constraint-satisfaction approach. Each VisitStage declares required resource kinds and capability tags. The solver finds a feasible allocation of resources across all concurrent stages in the time window, respecting capacity limits and provider availability.

graph TD
    VT[VisitType] --> VS1[Stage 1: CheckIn]
    VT --> VS2[Stage 2: Rooming]
    VT --> VS3[Stage 3: ProviderEval]
    VT --> VS4[Stage 4: Checkout]
    VS1 -->|requires| R_FD[FrontDesk Resource]
    VS2 -->|requires| R_MA[MA Resource]
    VS2 -->|requires| R_RM[ExamRoom Resource]
    VS3 -->|requires| R_MD[Provider Resource]
    VS3 -->|holds room| R_RM
    VS4 -->|requires| R_FD
  

Constraint Rules (12)

Appointment State Machine

stateDiagram-v2
    [*] --> Booked
    Booked --> Confirmed : Patient confirms (ReminderLadder)
    Booked --> Cancelled : Patient/staff cancels
    Booked --> Rescheduled : Reschedule requested
    Booked --> NoShow : Missed without cancel
    Confirmed --> CheckedIn : Front-desk / kiosk check-in
    Confirmed --> Cancelled : Late cancel
    Confirmed --> Rescheduled : Reschedule requested
    Confirmed --> NoShow : Missed without cancel
    CheckedIn --> InProgress : Roomed by MA/RN
    InProgress --> Completed : Provider signs off
    Rescheduled --> Booked : New appointment created
    NoShow --> [*]
    Cancelled --> [*]
    Completed --> [*]
  

Functional Requirements

1. P0 The system shall create, read, update, and soft-delete Schedules per provider per location with effective date ranges.
2. P0 The system shall auto-generate Slots from a Schedule template, respecting block-time windows and VisitType durations.
3. P0 The system shall enforce optimistic concurrency on Slot updates via ResourceVersion to prevent double-booking.
4. P0 The system shall transition Appointment status through the full state machine (Booked, Confirmed, CheckedIn, InProgress, Completed, NoShow, Cancelled, Rescheduled).
5. P0 The system shall fire an eligibility check when VisitType.RequiresEligibilityCheck is true and surface the result on the Appointment.
6. P0 The system shall support the resource-graph solver to allocate Resources (rooms, staff, equipment) across VisitStages.
7. P0 The system shall maintain a ReminderLadder on each Appointment, triggering SMS/email/voice at configurable cadence.
8. P0 The system shall support multi-channel booking (FrontDesk, Portal, Phone, WalkIn, WaitlistOffer) with channel recorded on each Appointment.
9. P0 The system shall enforce all 12 constraint rules during slot selection and booking.
10. P1 The system shall maintain a priority-scored Waitlist and auto-offer freed slots to the highest-scoring entry.
11. P1 The system shall expire WaitlistEntry offers after OfferExpires and re-queue the entry.
12. P1 The system shall track reschedule chains via RescheduledFromAppointmentID and warn at chain length > 3.
13. P1 The system shall support group visits via VisitType.ScheduleKind = GroupVisit with shared slot capacity.
14. P2 The system shall provide a provider utilization dashboard showing slot fill rate, no-show rate, and average wait time.

Non-Functional Requirements

• Latency: Slot availability query must return within 200 ms for a 30-day window.
• Concurrency: System must handle 50 concurrent booking attempts per location without data loss.
• Uptime: 99.9% availability for booking endpoints during business hours.
• Scalability: Support 500 providers and 10,000 appointments/day per organization.
• Audit Trail: Every state transition must be logged with actor, timestamp, and prior value.
• HIPAA: All PHI fields encrypted at rest (AES-256) and in transit (TLS 1.2+).
• Timezone: All timestamps stored as UTC; UI renders in practice-local timezone.
• Idempotency: Booking API must be idempotent; duplicate requests return the existing Appointment.
• Retention: Completed/Cancelled appointments retained for 7 years per HIPAA retention guidance.
• Accessibility: Scheduling UI must meet WCAG 2.1 AA, including keyboard-navigable calendar.

icApplication Overrides

How the Scheduling noun-apps are generated by IC on top of Cosmos DB + a constraint-solver library, surfaced as FHIR Schedule / Slot / Appointment, and dispatched through a pre-visit reminder ladder. The scheduling-engine is one of the few rev.health modules that ships a domain-specific binding override (the resource-graph component) on top of the IC default component generation.

Technology Stack P0

The shared platform stack (Cosmos DB, Redis, IC-generated API, Angular 21, SQS+SNS, OpenTelemetry, etc.) is documented in the IC Reference. Module-specific additions:

Project Directory Layout P0

This module uses a non-standard directory layout; the standard skeleton is documented in the IC Reference.

scheduling/
├── ami/
│   ├── Schedule.ami.json
│   ├── Slot.ami.json
│   ├── Appointment.ami.json
│   ├── Resource.ami.json
│   ├── VisitType.ami.json
│   ├── VisitStage.ami.json
│   └── WaitlistEntry.ami.json
├── container-definitions/   (generated by IC)
│   ├── 001_schedules.sql
│   ├── 002_slots.sql
│   ├── 003_appointments.sql
│   ├── 004_resources.sql
│   ├── 005_visit_types.sql
│   ├── 006_visit_stages.sql
│   ├── 007_waitlist_entries.sql
│   └── 099_rls_policies.sql
├── api/                              (generated by IC)
│   ├── schedules.controller.ts
│   ├── slots.controller.ts
│   ├── appointments.controller.ts
│   ├── resources.controller.ts
│   ├── visit-types.controller.ts
│   ├── visit-stages.controller.ts
│   └── waitlist.controller.ts
├── api-fhir/                         (FHIR facade; hand-written)
│   ├── schedule.fhir.mapper.ts
│   ├── slot.fhir.mapper.ts
│   └── appointment.fhir.mapper.ts
├── components/                       (generated + override)
│   ├── ic-ng21-schedule-1-app/
│   ├── ic-ng21-slot-1-app/
│   ├── ic-ng21-appointment-1-app/
│   ├── ic-ng21-resource-1-app/
│   ├── ic-ng21-visit-type-1-app/
│   ├── ic-ng21-waitlist-entry-1-app/
│   └── ic-ng21-scheduling-1-resource-graph/   (override binding)
├── lib/
│   └── scheduling-engine/            (OR-Tools wrapper + domain model)
│       ├── solver.ts
│       ├── resource-graph.ts
│       ├── stage-placement.ts
│       └── walk-in-insertion.ts
├── workers/
│   ├── reminder-ladder.worker.ts     (T-30 / T-14 / T-3 / T-day)
│   ├── no-show-detector.worker.ts    (T+10 sweeper)
│   └── waitlist-auto-fill.worker.ts  (5-min SMS offer)
├── env/
│   ├── dev.env
│   ├── qa.env
│   ├── uat.env
│   └── prod.env
└── tests/
    ├── solver.spec.ts
    ├── concurrency.spec.ts
    └── reminder-ladder.spec.ts

Scheduling code-gen details

The scheduling-engine library and FHIR facade are hand-written and consumed by the generated API layer.

Domain-Specific Override Bindings P1

One binding is overridden at the module level: the default ic-ng21-core-1-jtable for Slot is replaced by ic-ng21-scheduling-1-resource-graph. The default jtable presents Slots as a flat grid keyed on SlotStartDateTimeUTC; the resource-graph component renders Slots as paths through the resource graph and surfaces feasibility explanations inline.

Pre-Visit Reminder Ladder Dispatcher P1

The reminder dispatcher is a scheduled worker (reminder-ladder.worker.ts) that fires four reminders per appointment by default. The cadence is configurable per VisitType, but the v1 default is T-30, T-14, T-3, and T-day.

Worker behavior (pseudocode):

// Every minute, the worker scans the ReminderLadderState index for due rungs.
for each Appointment a in due_rungs(now):
  rung = a.next_due_rung()
  if !patient_opted_in(a.PatientID, rung.channel):
    skip_rung(a, rung, reason="opt-out")
    continue
  if a.AppointmentStatus in ["Cancelled", "NoShow", "Completed"]:
    cancel_remaining_rungs(a)
    continue
  body = render_template(rung.template, a)
  dispatcher.send(a.PatientID, rung.channel, body)
  audit_log.write(a, rung, "sent")
  a.ReminderLadderState = advance(a.ReminderLadderState, rung)
  persist(a)

The dispatcher runs on a 60-second tick. NFR-6 requires that 99.5% of messages dispatch within 5 minutes of their scheduled fire-time; the queue is sized to absorb 100K appointments-in-flight per tenant without breaching the SLA.

Versioning — Worked Example P0

Every versionable artifact in the Scheduling module follows IC SemVer per Hard Rule #9: break.feature.bug.buildtimestamp. The example below traces the lifecycle of the Slot AMI from its initial schema shape through a feature addition and a bug fix.

Scheduling environment details

Scheduling RBAC notes

ABAC overlays for patient-context apply (a patient sees only their own appointments).

Cross-Module Links

• Eligibility — EligibilityCheck triggered at booking/T-24h/check-in; result surfaced on Appointment.EligibilityStatus.
• Patient Portal — Self-scheduling for SelfSchedulable visit types; waitlist opt-in; reminder preferences.
• Clinical Documentation — Encounter created from completed Appointment; AppointmentID FK on Encounter.
• Task Management — NoShow triggers follow-up task; incomplete eligibility triggers front-desk task.
• Revenue Cycle Management — Completed Appointment feeds charge capture; VisitType maps to CPT/E&M level.

See also: Scheduling walkthrough · IC Reference