Skip to content

Backend Appointments and Scheduling

Ankit Upadhyay edited this page Jul 24, 2026 · 2 revisions

Backend: Appointments and Scheduling

The heart of the clinical workflow — the full appointment lifecycle, availability, rooms/in-patient, triage/occupancy, and encounters/cases. Part of Backend Overview.

What it owns

An appointment moves through: requested → accepted/rejected → checked-in → admitted → ready-for-billing → completed/no-show (see the state machine in the PIMS architecture guide). There are two route trees: a mobile one (pet-owner / object-scoped via requireMobileAuth, not role-based) and a PMS one (RBAC-guarded). This is the subsystem that most exercised the Prisma migration — now complete, with the dual-write/read-switch scaffold removed in PR #1819 (merged 2026-07-18); the active service is appointment.prisma.service.ts, with a legacy appointment.service.ts still alongside.

stateDiagram-v2
    [*] --> Requested
    Requested --> Accepted: accept (PMS)
    Requested --> Rejected: reject
    Accepted --> CheckedIn: check-in
    CheckedIn --> Admitted: admit (in-patient)
    CheckedIn --> ReadyForBilling: mark for billing
    Admitted --> ReadyForBilling
    ReadyForBilling --> Completed
    CheckedIn --> NoShow: no-show (worker)
    Completed --> [*]
Loading

Routers

appointment.router.ts, availability.router.ts, base-availability.router.ts, organisation-room.router.ts, room-unit.router.ts, room-unit-group.router.ts, service.router.ts, healthcare-service.router.ts, encounter.router.ts, episode-of-care.router.ts.

Controllers

web/appointment.prisma.controller.ts (active) + legacy web/appointment.controller.ts; web/availability.controller.ts, web/base-availability.controller.ts; web/organisation-room.controller.ts, web/room-unit.controller.ts (+ room-unit.controller.shared.ts), web/room-unit-group.controller.ts; web/service.controller.ts; web/case-encounter.controller.ts (exports EncounterController and CaseController).

Services

appointment.prisma.service.ts (active) + legacy appointment.service.ts; availability.service.ts, base-availability.service.ts; organisation-room.service.ts, room-unit.service.ts, room-unit-group.service.ts, room-management.helpers.ts; service.service.ts; case-encounter.service.ts; scheduling helpers in utils/scheduling.ts.

Models

appointment.ts, base-availability.ts, weekly-availablity-override.ts (sic), organisation-room.ts, occupancy.ts, service.ts.

Background jobs

queues/appointment.queue.ts (AppointmentQueue, job MARK_NO_SHOW) + queues/appointment.scheduler.ts + workers/appointment.worker.ts → AppointmentService.markNoShowAppointments. See Backend: Realtime, Chat, Jobs.

Notable

  • The active service exposes methods like createAppointmentFromPms, approveRequestedFromPms, checkInAppointment, admitAppointmentToInpatient, rescheduleFromParent, cancelAppointment — with business logic in transactional helpers (createAppointment wrapped in prisma.$transaction, upsertAppointmentOccupancy, ensureEncounterOnCheckIn).
  • In-patient care is modeled via rooms/room-units + occupancy; triage and encounters/episodes-of-care provide the clinical context around a visit.

Related

Product & Domain
Architecture
Applications
Design & Accessibility
Engineering Handbook
Decisions (ADRs)
Design Docs & Plans
Roadmap
Operations
Meta

Canonical code & docs: main repo · Auto-generated companion: DeepWiki

Clone this wiki locally