Vending Machine

Design a vending machine that supports product selection, inventory management, payments, dispensing, change, and failure recovery.

# Core requirements — must implement

• Support multiple products with different prices and available quantities.
• Allow customers to select a product using a product code.
• Accept coins and notes of different denominations, as well as card payments.
• Validate product availability and ensure sufficient payment before dispensing.
• Dispense the selected product after successful payment.
• Return change when cash payment exceeds the product price.
• Update inventory after successful dispensing.
• Handle invalid selections, out-of-stock products, and insufficient funds.
• Allow customers to cancel a purchase and return inserted cash when permitted.
• Support concurrent transactions without overselling inventory or corrupting purchase state.
• Provide admin operations to restock products and collect money.

# Extended requirements — discuss if time permits

• Handle payment failures, timeouts, retries, and uncertain payment outcomes.
• Detect whether exact change is available and manage coin inventory.
• Handle dispensing failures after payment, including refunds and transaction recovery after crashes.
• Support product expiration and out-of-service slots.
• Generate sales, inventory, and revenue reports.

# Non-functional requirements

• Correctness: Never dispense more units than are available or reserved for valid purchases.
• Consistency: Keep purchase, payment, and inventory states consistent, including after failures.
• Concurrency safety: Ensure simultaneous transactions cannot claim the same final unit.
• Extensibility: Make it easy to add payment methods and pricing or product rules.
• Testability: Allow payment providers and dispensing hardware to be replaced by test doubles.
• Recoverability: Recover or reconcile interrupted purchases after hardware failures or crashes.

# Explicit assumptions

# Solution

# Entities

They represent domain concepts and maintain their own valid state.

# Services — application workflows

• VendingMachineService
  • Orchestrates the purchase lifecycle: selection, payment, dispensing, cancellation, and completion
    • Validate the selection request.
    • Create and track the purchase.
    • Coordinate stock reservation and payment.
    • Request dispensing only after payment succeeds.
    • Complete the purchase after confirmed dispensing.
    • Coordinate cancellation and recovery.
    • Expose purchase status.
• InventoryService
  • Checks availability, reserves stock, confirms a sale, releases reservations, and supports inventory queries
• DispensingService
  • Interfaces with the dispenser hardware and reports success, failure, or uncertain outcomes
• RestockService
  • Restocks slots and updates stock records
• PaymentService
  • Processes cash/card payments, tracks payment status, and coordinates refunds.
  • Calculates change and checks whether sufficient denominations are available

# Extension points

• PaymentGateway : provide a separate implementation for each payment method.

# Design Patterns

# Strategy pattern — payment methods

Problem it solves: The vending machine can accept cash, cards, and potentially new payment methods in the future. Each method has a different way of processing payments.

Use Strategy to define a common interface and provide a separate implementation for each payment method.

The change algorithm can also use Strategy if the machine supports different policies.

For example:

• MinimumCoinCountStrategy: tries to return change using the fewest coins/notes.
• PreferredDenominationStrategy: prioritizes certain denominations.
• SimpleGreedyStrategy: takes larger denominations first, where the denomination system makes that approach valid

# State pattern — purchase lifecycle

Problem it solves: A purchase must not be allowed to perform arbitrary operations in arbitrary states.

A purchase can only perform certain actions in certain states

• Makes valid and invalid transitions explicit.
• Prevents operations that are illegal for the current lifecycle state.
• Makes failure recovery easier to reason about.

Purchase holds a reference to a state object. Instead of checking its status with repeated conditionals, it delegates the requested operation to that object

# Adapter pattern — payment provider and dispenser hardware

Problem it solves: External payment providers and vending hardware may expose different APIs and response formats.

The business logic shouldn't depend directly on those APIs.

• The application uses a consistent interface regardless of the vendor.
• Provider-specific request formats and response codes are isolated.
• Tests can substitute fake implementations.
• Replacing a vendor doesn't require rewriting the purchase workflow

# Factory pattern — creating payment strategies

The application needs the correct payment strategy based on the customer's selected method.

Factory and Strategy are complementary: the Factory chooses which strategy to provide; the Strategy performs the selected behavior.

# Observer pattern — notifications and monitoring

Problem it solves: Other components may need to react when a purchase completes, without being directly coupled to VendingMachineService.

Other parts of the system may need to react without being tightly coupled to the purchase workflow.

# Concurrency

# Idempotency

Problem : Imagine a payment request times out. The customer retries, or a client automatically resends the request.

An idempotency key identifies a logical operation so a repeated request can return the existing outcome instead of repeating the side effect.

The actual keys should be generated and managed consistently so retries of the same operation reuse the same key.

# Atomic reservation

Problem : Two customers buy the last unit, both customers can read quantity 1 and incorrectly proceed. This is a race condition, meaning the outcome depends on the timing of concurrent operations.

The availability check and reservation must behave as one indivisible operation

# Verfication