Scheduling & Availability Engine
Relevant source files
The following files were used as context for generating this wiki page:
- apps/api/src/modules/scheduling/availability.ts
- apps/api/src/modules/scheduling/routes.ts
- packages/db/prisma/migrations/20261007120000_scheduling/migration.sql
- apps/web/app/clinic/availability/schedule-card.tsx
- apps/api/test/scheduling.int.test.ts
- apps/web/app/clinic/availability/page.tsx
- apps/api/src/scripts/seed.ts
The Scheduling & Availability Engine manages the configuration of clinic locations, consultation modes, and doctor work hours. It calculates bookable time slots by combining weekly schedules with exceptions like leave or holidays. This engine supports multi-tenant isolation, ensuring that scheduling data remains private to each organization.
Sources: apps/api/src/modules/scheduling/availability.ts:1-76, apps/api/src/modules/scheduling/routes.ts:31-35
Core Data Model
The system uses several relational entities to define a doctor's availability within a specific clinic.
Key Entities
| Entity | Description |
|---|---|
clinics | Physical or virtual locations where consultations occur. |
consultation_types | Defines the mode (in-person, video, audio), duration, and fees. |
availability_versions | Stores a doctor's weekly schedule for a clinic and consultation type. |
availability_exceptions | Records specific deviations like leave, extra sessions, or clinic holidays. |
booking_rules | Organization-wide settings for booking horizons and same-day cutoffs. |
Sources: packages/db/prisma/migrations/20261007120000_scheduling/migration.sql:7-80
Relationship Diagram
The following diagram illustrates how scheduling entities relate to doctors and organizations.
Availability Versions
Availability is versioned by an effectiveFrom date. This allows doctors to plan future schedule changes without affecting past or current booking slots.
- Tidy Weekly Schedules: The engine drops days with no sessions and sorts session times chronologically.
- Validation: New schedules must start today or in the future. Sessions within a day cannot overlap.
- Deletion: You can only delete versions that have not yet started.
Sources: apps/api/src/modules/scheduling/availability.ts:78-103, apps/api/src/modules/scheduling/availability.ts:133-176
Weekly Schedule Structure
A WeeklySchedule is a JSON object where keys are weekdays and values are arrays of sessions.
{
"mon": [{ "start": "10:00", "end": "13:00" }, { "start": "17:00", "end": "20:00" }],
"sat": [{ "start": "10:00", "end": "13:00" }]
}
Sources: apps/api/src/modules/scheduling/availability.ts:78-86, apps/api/src/scripts/seed.ts:153-162
Availability Exceptions
Exceptions override the base weekly schedule for specific date ranges.
Exception Types
- Leave: A doctor-specific absence. It removes slots for the doctor across all clinics or specific ones.
- Holiday: A clinic-wide closure. It removes all slots for all doctors at that clinic.
- Extra Session: Additional consulting hours not covered by the weekly schedule.
Sources: apps/api/src/modules/scheduling/availability.ts:187-248, packages/db/prisma/migrations/20261007120000_scheduling/migration.sql:4
Constraints
- Exceptions cannot exceed 366 days in duration.
- The start time must precede the end time.
- Exceptions that have already started cannot be deleted.
Sources: apps/api/src/modules/scheduling/availability.ts:60-61, apps/api/src/modules/scheduling/availability.ts:250-281
Slot Generation Logic
The engine calculates slots dynamically for a specific date, doctor, clinic, and consultation type.
Slot Calculation Flow
The engine follows these steps to determine available time slots:
Statuses and Availability
Slots are marked as unavailable for several reasons:
- Past: The slot time has already passed.
- Cutoff: The slot falls within the
sameDayCutoffMinuteswindow (for patient bookings). - Busy: An appointment already exists in that time slot.
- Beyond Horizon: The date exceeds the
horizonDayssetting.
Sources: apps/api/test/scheduling.int.test.ts:290-298, apps/api/src/modules/scheduling/availability.ts:333-344
API Interface
The AvailabilityService exposes endpoints for managing scheduling data.
Primary Endpoints
| Method | Path | Access Role |
|---|---|---|
GET | /availability/versions | Staff |
POST | /availability/versions | Doctor, Clinic Admin |
DELETE | /availability/versions/:id | Doctor, Clinic Admin |
GET | /slots | Staff |
Sources: apps/api/src/modules/scheduling/routes.ts:80-99, apps/api/src/modules/scheduling/routes.ts:117-120
Security and Tenancy
The engine enforces strict access controls and data isolation.
- Row-Level Security (RLS): The database uses Postgres RLS to ensure a tenant only sees their own clinics, schedules, and exceptions.
- Role-Based Access: Clinic admins manage global settings and holidays. Doctors manage their own leave and weekly schedules.
- Audit Logging: The service records an audit log for every creation or deletion of a version or exception.
Sources: packages/db/prisma/migrations/20261007120000_scheduling/migration.sql:160-205, apps/api/src/modules/scheduling/availability.ts:162-171, apps/api/src/modules/scheduling/availability.ts:237-245