Requirements for the Vending Machine

Let's define exactly what our Vending Machine system needs to do. Each requirement is specific, testable, and will directly drive a design decision in our class diagram and implementation.

Product & Inventory:

1. R1: The vending machine shall hold multiple product types (e.g., Coke, Pepsi, Water, Chips), each with a name, a price, and a current stock quantity.
2. R2: Each product slot shall track its own inventory count. When a product's count reaches zero, that product is marked unavailable.
3. R3: An operator shall be able to restock products — adding quantity to existing slots or introducing new products.

Coin Handling & Payment:

4. R4: The machine shall accept coins of predefined denominations: penny (1¢), nickel (5¢), dime (10¢), and quarter (25¢). No bills, no cards (we'll extend to multiple payment methods later).
5. R5: The machine shall maintain a running balance of all coins inserted during the current transaction.
6. R6: When the inserted amount exceeds the product price, the machine shall return the correct change in coins.
7. R7: A user may request a full refund of inserted coins at any point before a product is dispensed.

Product Selection & Dispensing:

8. R8: The user shall select a product by specifying its identifier (e.g., slot code or product name).
9. R9: If the selected product is in stock AND the inserted balance is sufficient, the machine shall dispense the product and return any change.
10. R10: If the selected product is out of stock, the machine shall notify the user and allow them to select a different product or request a refund.
11. R11: If the inserted balance is insufficient for the selected product, the machine shall notify the user of the shortfall and allow them to insert more coins or request a refund.

State Management:

12. R12: The machine shall be in exactly one state at any time: Idle, HasMoney, Dispensing, or OutOfStock.
13. R13: State transitions shall be triggered by user actions (insert coin, select product, request refund) or system events (product dispensed, all products depleted, restock).
14. R14: Invalid actions for the current state (e.g., selecting a product when no money is inserted) shall be rejected with a meaningful message.

Beyond what the system does, here's how well it should do it:

1. Extensibility (Open/Closed Principle): Adding a new state (e.g., "Maintenance") or a new payment method (e.g., credit card, mobile pay) must NOT require modifying existing state classes or the core VendingMachine class. New behavior is added by introducing new classes, not editing old ones (Fundamentals S6).

2. Single Instance: There shall be exactly one VendingMachine instance managing the shared inventory. Multiple entry points must not create duplicate machines with conflicting inventory counts (Singleton Pattern — Fundamentals S10).

3. Thread Safety (Stretch): While our initial design targets a single-user machine, the design should be structured so that thread safety can be added later without a rewrite — particularly around inventory updates and balance tracking.

4. Testability: Each component — state transitions, inventory management, coin arithmetic — must be testable in isolation. States should be injectable for unit testing.

5. Correctness of Change Calculation: The machine must always return the minimum number of coins as change. Given the coin denominations {25¢, 10¢, 5¢, 1¢}, a greedy approach is provably optimal. Incorrect change amounts are unacceptable.

In Scope:

• Product inventory (CRUD for products, stock tracking)
• Coin insertion, balance accumulation, change return
• State machine with 4 states: Idle, HasMoney, Dispensing, OutOfStock
• Product selection with stock and balance validation
• Refund mechanism
• Singleton machine instance
• Python and Java implementations

Out of Scope:

• Bill/card/mobile payments (covered in the Extension tutorial)
• Real hardware integration (coin validators, motors, displays)
• REST API or web interface
• Persistent database storage
• Multi-machine networking or cloud telemetry
• User authentication or operator login
• Currency other than US coins

We're modeling the logic of a vending machine, not building its embedded firmware.

Every requirement must map to at least one class or method. Here's a preview of how our requirements will drive the design:

Requirement	Drives Which Classes/Components
R1 (product types with name, price, qty)	Product class, Inventory class
R2 (per-slot stock tracking)	Inventory.checkStock(), Inventory.reduceStock()
R3 (operator restock)	VendingMachine.restock() or Inventory.addStock()
R4 (coin denominations)	Coin enum (PENNY, NICKEL, DIME, QUARTER)
R5 (running balance)	currentBalance attribute in VendingMachine or state context
R6 (return change)	Change calculation logic in DispensingState or utility
R7 (full refund)	refund() method triggered from HasMoneyState
R8-R11 (select, validate, dispense)	selectProduct() on states, Inventory checks
R12-R14 (state machine)	VendingMachineState interface + concrete state classes

We'll revisit this table when building the class diagram to verify every requirement is accounted for.

In a real interview, spend 3-5 minutes clarifying requirements before jumping into design. The Vending Machine seems simple, but smart clarifying questions impress interviewers:

• "Should the machine support bills and cards, or just coins?" — Scopes the payment system.
• "Is there a single machine or a fleet? Do we need a central management system?" — Establishes single vs. distributed scope.
• "Can the user select a product before inserting money, or must money come first?" — Determines state transition order.
• "How should the machine behave when it can't make exact change?" — Reveals an important edge case.
• "Is there a maintenance state for operator servicing?" — Shows you think about operational states beyond the happy path.

These questions demonstrate that you think about edge cases and scope boundaries — exactly what interviewers look for.