Design a Vending Machine

Design the object model and core APIs for a self-contained vending machine controller — the software that runs on the machine itself, driving its keypad, coin slot, hopper, and dispensing motors.

Operating context. One physical machine with a fixed grid of product slots (say 30–60 slots), each slot holding one product type at a set price and a small count of units. A shopper walks up, inserts coins one at a time, selects a slot, and the machine either dispenses the item and returns any change, or refunds the inserted money. Only one shopper interacts at a time, but coin insertion, selection, and cancel arrive as discrete events the controller must handle in order. The machine keeps a coin bank (its float) used to make change. No network — everything is in-process on the machine's embedded board.

Out of scope. The physical hardware drivers (motor timing, coin-validator electronics), the restocking/admin console UI, persistence across power loss, telemetry or fleet management, and any card/contactless reader wiring (design the seam for it, but do not build it).

What to produce. The class hierarchy (entities, value objects, controller/services), the public API each class exposes, and above all the state machine the controller runs: the states (idle, collecting money, dispensing, and any others you need), the events that drive transitions (insert coin, select slot, cancel, dispense-done), and the actions on each transition. Be explicit about: how inventory is tracked per slot, how change is computed from the coin bank and what happens when exact change is impossible, how a cancel/refund returns the shopper's money, and how a second payment method (a card reader) could be added later without rewriting the state machine.