Problem statement
Design the object model and public APIs for a reusable waitlist component that any capacity-limited resource (a class, a restaurant table, a product drop) can embed to queue people fairly and promote them the moment a spot opens.
Operating context. A resource has limited capacity. When it is full, requesters join a waitlist and receive a position; when a held spot is released, the manager promotes the front-most eligible entry and notifies it. Entries may carry a priority tier (VIP ahead of standard) and can leave the list, which shifts positions. A promoted entry has a claim window to accept before the offer rolls to the next entry. The component is generic over the resource it fronts and runs in a single process, one wall clock.
Out of scope. The notification transport (email / SMS / push — model only the hook), the fronted resource's own booking logic, the REST surface, and persistence (assume in-memory for v1).
What to produce. The class hierarchy (Waitlist, Entry, promotion policy, notifier hook, manager service), each class's public API, and the entry state machine (waiting → offered → claimed / expired / left). Be explicit about: how positions stay correct as entries join, leave, and are promoted, how the ordering rule (FIFO vs priority-tier) is pluggable, and how promotion fires as an event so the fronted resource stays decoupled.
Must do 5
Functional requirements
- Join the waitlist and receive a stable position under the active ordering rule.
- Promote the front-most eligible entry to offered when a spot is released.
- Accept an offer within its claim window, or expire it and roll to the next entry.
- Leave the waitlist at any time, correctly shifting the positions behind.
- Report an entry's current position and the overall waitlist depth.