Scheduling & Appointments

Scheduling & Appointments

Who this is for: support staff, care-team staff, doctors, new hires.

Two kinds of services: appointment-based and automatic

Not every service requires a live appointment. Each service is configured (per state) with whether it requires an appointment and, if so, the appointment length and how much buffer time to leave between appointments.

• Appointment-based services — the patient books a time slot with a doctor after completing the intake form.
• Automatic-assignment services — no appointment is booked. Instead, the case is automatically assigned to an available doctor in the background, based on which doctors are set up to handle that service and state, and factoring in each doctor’s current workload and any configured priority weighting.

Booking an appointment (patient side)

1. After completing the earlier case steps, the patient reaches a booking page.
2. The system shows available days/times based on:
   • The doctor(s) who are able to see this type of case, in the patient’s state
   • Each doctor’s working hours (including split shifts and overnight shifts)
   • Each doctor’s approved time off
   • A booking window — by default the next 14 days, but each service/state/tag combination can configure its own window in its service configuration
   • A minimum notice period — patients cannot book a slot starting less than 30 minutes from now (this 30-minute figure is currently fixed platform-wide, not configurable per service)
   • A concurrency limit — by default only 1 patient can be booked into the same doctor’s same time slot at once, but this is also configurable per service/state/tag (a slightly larger number could allow batching multiple patients per slot for a service that supports it)
   • Appointment length and buffer time between appointments — both default-driven (15 minutes appointment, 0 minutes buffer) but configurable per service/state/tag
3. The patient selects a slot; the system re-validates it’s still in the future and that the doctor still has capacity in that slot (re-checking the same concurrency limit) before confirming the booking — this closes the gap where two patients might try to grab the same slot at nearly the same moment.
4. Once booked, the patient gets a join link for their appointment (a default video-call link is used unless the specific appointment has its own link configured).
5. Patients can reschedule if their booked slot has expired or no longer works.

Where numbers above say “default,” that means the service configuration didn’t set its own value — see Services Catalog for how per-service/state settings work. An admin changes actual booking-window/concurrency/duration numbers for a specific service by editing that service’s configuration, not by editing code.

Doctor availability (care portal side)

• Doctors’ regular working hours are configured in the care portal.
• Doctors (or admins on their behalf) can record time off, which blocks new bookings during that window.
• For automatically-assigned (non-appointment) services, a relaxed version of the time-off check is used (looking about a week ahead) when picking which doctor to assign a case to.

Appointment reminders

Once an appointment is booked, the system automatically schedules four reminders to the patient, each sent by both email and text message: 48 hours before, 24 hours before, 2 hours before, and 15 minutes before the appointment. If an appointment is rescheduled, this same set of four reminders is rebuilt around the new time. See Messaging & notifications for how reminders are delivered.

Calendar technology

The patient-facing booking flow (available slots, doctor filtering, time-off checks, booking confirmation) is fully custom-built in the patient portal — it does not call any outside calendar/scheduling product to generate availability or confirm a booking.

The care portal separately still has database fields (calComEmail, calComUrl) and a webhook route referencing a third-party scheduling tool (“Cal.com”), which was confirmed to be a legacy integration no longer in active use, not the system that powers booking today. It’s called out here only so nobody mistakes it for the live scheduling mechanism.

Open questions

• Whether patients can cancel (not just reschedule) a booked appointment from their own dashboard was not confirmed.
• Whether the legacy Cal.com webhook route and its associated database fields are safe to remove, or still referenced by some other still-active process, was not confirmed.

Where this comes from

• parkingmd-patient-portal/documentation/service-flow.md (fulfillment path, appointment steps)
• parkingmd-patient-portal/documentation/routing.md (/task/[taskid]/book, /schedule, /reschedule)
• parkingmd-patient-portal/src/trpc/routers/appointment/ (availability.ts, assign.ts, selection.ts, index.ts — including the MIN_BOOKING_NOTICE_HOURS, appointmentBookingWindowDays, appointmentConcurrencyLimit, appointmentDurationMinutes, appointmentBufferMinutes values/defaults, and getJoinLink)
• parkingmd-patient-portal/src/models/ (appointments.ts, doctors.ts)
• parkingmd-care-portal/src/lib/timeOff/
• parkingmd-care-portal/src/lib/appointment-reminders/action.ts (scheduleAllAppointmentReminders, scheduleAllRescheduledAppointmentReminders — the 48h/24h/2h/15m reminder schedule)
• parkingmd-care-portal/docs/care-portal-kt-guide.md
• parkingmd-care-portal/src/app/api/webhooks/calcom/route.ts (legacy, not the current booking mechanism — kept as a live route but confirmed unused in practice)
• parkingmd-care-portal/src/app/api/webhooks/calcom/care-team/route.ts (present but fully commented out — dead)
• parkingmd-care-portal/src/server/db/schema.ts (calComEmail, calComUrl, calComWebhookLogs — legacy fields)