Design a Hospital Appointment System

Design the object model and public APIs for the scheduling core of a hospital appointment system: the object graph that holds doctors, their bookable time slots across specialties, and patient bookings, plus the rules that keep two patients from ever holding the same slot. This is the in-process kernel a web or mobile layer would drive, not the UI or the persistence tier.

Operating context. One hospital, tens of doctors grouped by specialty (cardiology, dermatology, pediatrics, and so on). Each doctor publishes availability as discrete, non-overlapping slots of a fixed length on given days. A patient searches by specialty (optionally by a specific doctor), sees open slots, and books one; a booked slot becomes unavailable to everyone else. A patient can reschedule to another open slot or cancel, which frees the slot. When a desired slot is already taken, the patient may join that slot's waitlist; if it later frees, the first waiter is offered it. Held-but-unconfirmed bookings expire after a grace window, decided by an injected clock so behavior is testable. A single thread need not be assumed — several patients may act on the same doctor's calendar at once.

Out of scope. The persistence layer (assume in-memory for v1), the REST/RPC transport and auth, notification delivery (email/SMS bodies and gateways — model only the intent to notify), payment and insurance billing, and clinician-side EHR / medical records. Focus on the in-process object model, not the wire or storage layer.

What to produce. The class hierarchy (entities, value objects, and the scheduling service), the public API each class exposes, and the state transitions of a slot (open -> held -> booked -> completed, plus cancelled and expired) and of a booking. Be explicit about: how availability slots are generated and represented without overlap; how a concurrent double-book on the same slot is prevented; how search narrows by specialty and doctor; how reschedule and cancel move a slot between states and trigger the waitlist; how the waitlist decides who is offered a freed slot; and how the grace-window expiry uses an injected clock so a test can force a slot to lapse.