Requirements

Functional Requirements:

1. Dispense various itmes
2. Manage inventory of the items
3. Handle different payment types
   1. Coins
   2. Cash
   3. Cards
4. Provide maintenance alerts

Non-Functional Requirements:

• Thread Safety (Concurrency): The vending machine system must be thread-safe. If multiple threads attempt to read or modify the machine's state simultaneously (for example, a user purchasing an item at the exact moment a technician updates the inventory), the system must prevent race conditions and maintain data consistency.
• Extensibility: The design should make it easy to add new features later (such as supporting mobile contactless payments or adding new categories of items) without rewriting the core vending machine logic. Utilizing OOD patterns like the State Pattern (for machine states) or the Strategy Pattern (for payment methods) is highly recommended.
• Maintainability: The system should exhibit high cohesion and low coupling. Core responsibilities—such as payment handling, inventory tracking, and physical dispensing—should be separated into distinct classes to make the system easy to test, debug, and maintain.
• Fault Tolerance & Reliability: The system must fail gracefully. If a payment fails, card processing times out, or an item fails to dispense, the machine must roll back its transaction state and ensure the user is not incorrectly charged.

Core Objects & Relationships

1. VendingMachine (Controller/Co-ordinator) : Central controller of system, it co-ordinates overall flow, maintains active state (idle, accepting payment, dispensins) and delegates tasks to helper components. Typically designed as singleton since there is only one physical machine instance
2. Item (Data Object): Represents a product available in machine (e.g soda, chips, canday), it contains basica attributes like name, price & id
3. Slot (Entity): Represents a physical lane or rack inside the vending machine. Each slot has a unique identifier, holds a specific Item and tracks its own capacity/quantity
4. Inventory (Management Class): Managers the collection of slots. It provides methods to add itesm, check stock levels and decrement stock when an item is succesfully dispensed.
5. Payment (interface/abstrac class): Defines the contract for processing transaction. To support required payment type use stragety pattern with conceret subclasses
   1. coinpayment (physical coin insertion)
   2. cashpyaments (paper currency validation)
   3. cardpayment (handle cred/debit processing via external reader)
6. AlertSystem: Monitors system health and triggers maintenance alerts when errors occurs, such as physical dispenser jam or when iventory levels drop below a dcritical threshold

Relationships & Associations

1. VendingMachine has an Inventory
2. VendingMachine has VendingMahineState
3. VendingMachine uses Payment
4. Vending communicates with AlertSystesm

APIs & Class Members

For each class, define the attributes (data) it will hold and the methods (functions) that operate on the attributes. Ensure they align with the object's responsibilities and adhere to the principle of encapsulation. Write your code in the code editor below.

Deep Dive

1. Design Tradeoffs Considered

• State Pattern vs. Conditional Logic (If-Else Blocks)
  • Tradeoff: Boilerplate and class overhead versus code readability and maintainability.
  • Decision: We chose the State Pattern (IdleState, PaymentPendingState, etc.). Using standard if-else or switch-case statements inside a central controller would require checking state variables during every input (if self.state == IDLE... else if self.state == PAYMENT_PENDING...). As we add states (e.g., OutOfOrder, Refilling, Testing), this code quickly becomes unmanageable. Isolating actions into state classes keeps the core transition engine clean, though it increases the number of classes.
• Singleton Pattern vs. Dependency Injection
  • Tradeoff: Strict single-instance safety versus easy mock testing.
  • Decision: The VendingMachine represents a physical, localized controller, so we designed it using a double-checked locking Singleton pattern with Python's threading.Lock. This guarantees that multiple threads cannot initialize competing controller instances. While Singletons can sometimes make mock testing harder, we isolated the underlying dependencies (Inventory, AlertSystem, PaymentStrategy) so they can still be injected and stubbed out independently during unit testing.
• High-Level Payment Strategies vs. Low-Level Denomination Tracking
  • Tradeoff: Abstract mathematical transactions versus modeling physical coin/cash vaults.
  • Decision: Our PaymentStrategy abstracts payments down to checking if a numeric threshold is met and calculating change mathematically. To keep the initial design clean, we traded off low-level hardware bin tracking (e.g., tracking the exact count of nickels, quarters, and dollar bills inside physical coin rollers). We note this as a prioritized future enhancement.

2. Adherence to SOLID Principles

The architecture strictly adheres to all five SOLID principles of software design:

• S – Single Responsibility Principle (SRP): Each class has exactly one reason to change.
  • Item acts solely as a product metadata holder.
  • Slot and Inventory deal only with storage and physical capacity limits.
  • PaymentStrategy subclasses are concerned strictly with executing transaction logic.
  • VendingMachineState classes govern only step-by-step state logic.
  • VendingMachine coordinates interactions but delegates actual task executions.
• O – Open/Closed Principle (OCP): The codebase is open for extension but closed for modification.
  • Need to support a new payment method like Mobile Contactless (NFC) or Bitcoin? Simply implement a new PaymentStrategy subclass; the core state transitions remain completely untouched.
  • Need to add a maintenance test state? Implement a new VendingMachineState class without modifying the existing states.
• L – Liskov Substitution Principle (LSP): Subclasses can seamlessly replace their parents.
  • Any VendingMachineState subclass can be supplied to VendingMachine.set_state() without breaking the system’s behavior.
  • Any PaymentStrategy (CoinPayment, CashPayment, CardPayment) can be passed to insert_payment and processed identically because they all strictly conform to process_payment() -> bool.
• I – Interface Segregation Principle (ISP): Since Python does not have native static interfaces, we use clean Abstract Base Classes (ABC). Both PaymentStrategy and VendingMachineState define only the minimal, essential methods that their subclasses must implement, ensuring that no class is forced to carry bloated, unused code.
• D – Dependency Inversion Principle (DIP): The VendingMachine orchestrator depends on abstractions rather than concrete classes. It does not directly couple itself to CardPayment or IdleState. Instead, it interacts with the abstract PaymentStrategy and VendingMachineState interfaces, allowing implementations to remain loosely coupled.

3. Handling Changes in Scale

• From In-Memory to Persistent Storage: Currently, the Inventory stores slot configurations in memory using a Python dictionary. For a fleet of commercial vending machines, the Inventory can easily be refactored to query a local SQLite database or interface with an ORM (e.g., SQLAlchemy) to persist stocks.
• High Concurrency: Physical vending machines are subject to asynchronous inputs (such as external sensory telemetry, card readers, and manual button presses arriving simultaneously). By wrapping API calls (select_item, insert_payment, cancel_transaction) in with self.state_lock:, we prevent race conditions from corrupting the internal state of the machine.
• Central Fleet Telemetry: To scale to thousands of machines, the AlertSystem can be modified to push maintenance warnings to a remote messaging queue (e.g., MQTT or AMQP) rather than printing to stdout. This allows centralized servers to dispatch technicians instantly.

4. Easy Extension of New Functionalities

• Dynamic Pricing & Discounts: Because the pricing is queried from Slot.item.price at the moment of payment, we can easily inject a DiscountService or dynamic pricing engine into the machine. This allows modifying pricing (e.g., happy hour discounts or card-processing surcharges) during PaymentPendingState without rewriting state structures.
• Handling Multi-Buy and Cart Transactions: If we want to allow users to select multiple items before paying, we can introduce a Cart class and update PaymentPendingState to hold an active list of selected slots instead of a single selected_slot_id.

5. Areas for Future Improvement

1. Observer Pattern for Alerts: Instead of hardcoding references to AlertSystem inside state transitions, implement a true Pub-Sub mechanism. The vending machine would publish events (e.g., OUT_OF_STOCK, DISPENSER_JAMMED), and observers (a local LED display, a remote telemetry dashboard, a diagnostic log file) would handle them independently.
2. Physical Denomination Cash Ledger: Build out an explicit physical bin ledger within the coin/cash payment processing system. Tracking the inventory of physical change (such as counting the number of dimes and quarters) is required to dynamically flag "Exact Change Only" mode if coin supplies run low.
3. Hardware Abstraction Layer (HAL): To prepare this software for deployment on an actual machine, we should introduce a HAL interface. This layer would translate software calls (like slot.dispense()) into low-level electrical signals for the motors and check physical infrared drop-sensors to verify that an item actually fell into the dispenser pocket.