Vending Machine

Everyone knows how a vending machine works. Insert money, press a button, get your snack. It takes 30 seconds in real life and about 20 lines of code to fake. But what happens when the machine needs to track states? When customers pay with cards instead of coins? When you need to calculate change using the fewest coins possible via a greedy algorithmA problem-solving strategy that always picks the locally best option at each step. For coin change with standard denominations (quarter, dime, nickel, penny), the greedy approach — always use the biggest coin that fits — gives the optimal result.? When 500 machines need a central dashboard? That simple vending machine becomes a real design problem with real patterns hiding inside.

We're going to build this machine 7 times — each time adding ONE constraintA real-world requirement that forces your code to evolve. Each constraint is something the BUSINESS needs, not a technical exercise. "The machine has different states" is a constraint. "Use the State pattern" is not — that's a solution you DISCOVER. that breaks your previous code. You'll feel the pain, discover the fix, and understand WHY the design exists — not just what it looks like. By Level 7, you'll have a complete, production-grade vending machine system. But more importantly, you'll have a set of reusable thinking tools that work for ANY system — elevators, chess, parking lots, anything. These are transferable skillsThe techniques you learn here (What Varies?, What If?, CREATES) work because they target the STRUCTURE of problems, not the domain. Every system has entities, varying algorithms, concurrency risks, and edge cases — regardless of whether it vends snacks or parks cars..

Before we touch a single line of code, let's walk up to a real vending machine. Not a simulated one — the kind you see in an office break room or a train station. Watch what happens step by step, and pay attention to every thing (noun) and every action (verb) you encounter. These become your classes, methods, and data types.

Every complex system starts with a laughably simple version. For a vending machine, that means: accept money, check if it's enough, and dispense one fixed product. That's it. No variety, no states, no change. The goal of Level 0 is to get something working — then let the next constraint break it.

Your Internal Monologue

"Simplest possible... one product, fixed price, coins only. I literally just need: accept money, check if enough, dispense. A single class with a balance field and two methods. That's it."

"Should I create a Product class? A Payment class? A Dispenser class? ...No. There's ONE product with ONE price. Splitting that into three classes would be premature abstractionCreating abstractions (interfaces, base classes, separate classes) before you have a concrete reason to. At Level 0, a Product class adds complexity without solving any problem. Wait until a constraint FORCES you to separate concerns.. I'll keep it all in one class and let the constraints tell me when to split."

"For the balance — decimal not double. Money should always use decimalIn C#, decimal is a 128-bit type designed for financial calculations. Unlike double (which uses binary floating-point and can produce rounding errors like 0.1 + 0.2 = 0.30000000000000004), decimal uses base-10 arithmetic — perfect for money. to avoid floating-point rounding errors."

How Level 0 Works

// Three classes for a single-product machine? Overkill.
public class Product { public string Name; public decimal Price; }
public class PaymentProcessor { public decimal Balance; public void Accept(decimal amount) => Balance += amount; }
public class Dispenser { public int Stock; public bool Dispense() { Stock--; return true; } }

public class VendingMachine
{
    private readonly Product _product = new() { Name = "Drink", Price = 1.50m };
    private readonly PaymentProcessor _payment = new();
    private readonly Dispenser _dispenser = new() { Stock = 10 };
    // ... orchestration code to wire them together ...
}

public class VendingMachine
{
    private decimal _balance;
    private const decimal Price = 1.50m;
    private int _stock = 10;

    public void InsertCoin(decimal amount)
    {
        _balance += amount;
    }

    public string SelectProduct()
    {
        if (_stock <= 0) return "Out of stock";
        if (_balance < Price) return $"Insert {Price - _balance:C} more";
        _balance -= Price;
        _stock--;
        return "Dispensed! Enjoy your drink.";
    }
}

Here's the complete Level 0 code. Read every line — there are only 15 of them.

public class VendingMachine
{
    private decimal _balance;
    private const decimal Price = 1.50m;
    private int _stock = 10;

    public void InsertCoin(decimal amount)
    {
        _balance += amount;
    }

    public string SelectProduct()
    {
        if (_stock <= 0) return "Out of stock";
        if (_balance < Price) return $"Insert {Price - _balance:C} more";
        _balance -= Price;
        _stock--;
        return "Dispensed! Enjoy your drink.";
    }
}

Let's walk through what each piece does:

• _balance — how much money the customer has inserted so far. A decimal because money needs exact arithmetic (no floating-point surprises like 0.1 + 0.2 = 0.30000...4).
• Price — a compile-time constantThe const keyword means this value is baked into the code at compile time. It can never change while the program runs. Perfect for Level 0's single fixed price. (Level 1 will replace this with per-product prices.) of $1.50. One product, one price. Simple.
• _stock — how many drinks remain. Starts at 10. Every successful purchase decrements it.
• InsertCoin() — adds the coin value to the running balance. No validation yet (we'll add that later). Just accumulate.
• SelectProduct() — the entire "business logic." Check stock, check balance, deduct and dispense. Three lines of logic, three possible outcomes.

15 lines. It works for a toy machine. But can you spot what's missing? There's no concept of different products, no state management, no change calculation, no payment options, and the balance never resets after dispensing. We'll feel each of these pains in the coming levels.

Growing Diagram — After Level 0

A real vending machine has rows of different products at different prices. Our Level 0 code treats the entire machine as a single-product dispenser — like a gumball machine. To support variety, we need to model what a product IS, where it lives, and how to look it up by slot code.

Your Internal Monologue

"Multiple products... I need to store them somewhere. A Product has name, price, category. Do these products behave differently? Does a bag of chips dispense differently from a can of soda? No — the machine dispenses them all the same way. They're just data."

"So Product should be a record, not a class with inheritance. And slots map codes to products. A DictionaryA key-value lookup structure in C#. Dictionary<string, Slot> lets you look up a Slot by its code (like "A1" or "B3") in constant time — exactly what you need when a customer presses a button. from slot code to Slot should work. Customer presses 'B2', we look up _slots["B2"] — instant."

"Do I need a ChipsSlot vs. SodaSlot? Same question: do slots behave differently based on product type? No. Every slot holds a product and has a quantity. One Slot class for all."

The Slot Grid

Record or Class? The Decision Tree

public abstract class Product { public abstract string Name { get; } public abstract decimal Price { get; } }
public class ChipsProduct : Product { public override string Name => "Chips"; public override decimal Price => 1.50m; }
public class SodaProduct : Product { public override string Name => "Soda"; public override decimal Price => 2.00m; }
public class WaterProduct : Product { public override string Name => "Water"; public override decimal Price => 0.75m; }
// Adding a new product = new class. 50 products = 50 classes. Yikes.

// Parallel arrays — fragile and error-prone
string[] names = { "Chips", "Soda", "Water" };
decimal[] prices = { 1.50m, 2.00m, 0.75m };
int[] quantities = { 8, 10, 12 };

// Accessing product 1: names[1], prices[1], quantities[1]
// Add a product? Update ALL THREE arrays in sync.
// Delete one entry? Now indices are wrong. Welcome to Bug City.

public readonly record struct Product(string Name, decimal Price, string Category);

public class Slot
{
    public string Code { get; }
    public Product Product { get; }
    public int Quantity { get; private set; }

    public Slot(string code, Product product, int quantity)
        => (Code, Product, Quantity) = (code, product, quantity);

    public bool HasStock => Quantity > 0;
    public void Decrement() => Quantity--;
}

// Usage: _slots["B2"].Product.Price → $1.75

Here's the updated VendingMachine that supports multiple products and slots.

/// A product is pure data — name, price, category.
/// No behavior, no identity, no mutability. A perfect record.
public readonly record struct Product(string Name, decimal Price, string Category);

/// A slot is a physical position in the machine.
/// It holds a product and tracks how many are left.
public class Slot
{
    public string Code { get; }
    public Product Product { get; }
    public int Quantity { get; private set; }

    public Slot(string code, Product product, int quantity)
        => (Code, Product, Quantity) = (code, product, quantity);

    public bool HasStock => Quantity > 0;
    public void Decrement() => Quantity--;
}

public class VendingMachine
{
    private decimal _balance;
    private readonly Dictionary<string, Slot> _slots = new();

    public VendingMachine()
    {
        // Load products into slots
        _slots["A1"] = new Slot("A1", new Product("Chips", 1.50m, "Snacks"), 8);
        _slots["A2"] = new Slot("A2", new Product("Soda", 2.00m, "Drinks"), 10);
        _slots["A3"] = new Slot("A3", new Product("Water", 0.75m, "Drinks"), 12);
        _slots["B1"] = new Slot("B1", new Product("Candy", 1.25m, "Snacks"), 15);
        _slots["B2"] = new Slot("B2", new Product("Cookies", 1.75m, "Snacks"), 6);
    }

    public void InsertCoin(decimal amount) => _balance += amount;

    public string SelectProduct(string slotCode)
    {
        if (!_slots.TryGetValue(slotCode, out var slot))
            return $"Invalid slot: {slotCode}";
        if (!slot.HasStock)
            return $"{slot.Product.Name} is out of stock";
        if (_balance < slot.Product.Price)
            return $"Insert {slot.Product.Price - _balance:C} more";

        _balance -= slot.Product.Price;
        slot.Decrement();
        return $"Dispensed {slot.Product.Name}! Enjoy.";
    }
}

Let's walk through the key changes from Level 0:

• Product record — one line replaces the old const decimal Price. Each product knows its own name, price, and category. Adding a new product is adding one constructor call, not creating a new class.
• Slot class — wraps a Product with a mutable Quantity. The private setterThe private set means only the Slot class itself can change Quantity (via the Decrement method). Outside code can read it but can't tamper with it. This protects inventory integrity. means only Decrement() can change the stock — external code can read it but can't tamper.
• Dictionary lookup — _slots["B2"] finds the slot in constant time. The TryGetValue pattern avoids exceptionsAn exception is C#'s mechanism for signaling errors. But exceptions should be for EXCEPTIONAL situations (file not found, network down), not expected business cases like "invalid slot code." Using TryGetValue returns false instead of throwing, which is cheaper and cleaner. when someone enters an invalid code.
• SelectProduct(slotCode) — now takes a slot code parameter. Three checks in order: valid slot? in stock? enough balance? Each early return tells the customer exactly what's wrong.

Growing Diagram — After Level 1

Here's the core insight: the vending machine behaves completely differently depending on what mode it's in. When it's idle, inserting a coin transitions it to "has money." When it's dispensing, inserting a coin should be rejected. When it's out of service, EVERYTHING should be rejected. The same action produces different results depending on the current state.

When you find yourself writing if (state == X) doThis; else if (state == Y) doThat; in every single method, that's a code smell with a name. Let's discover the fix.

Your Internal Monologue

"I could add if (_state == State.Idle) checks to every method... but that means every new state adds a new branch to every method. 4 states × 4 methods = 16 branches. Add 'Maintenance' mode? Touch all 4 methods. That violates OCPThe Open-Closed Principle: classes should be open for extension but closed for modification. Adding new behavior should mean adding new code (a new class), not modifying existing code (editing switch statements in existing methods).. And it violates SRPThe Single Responsibility Principle: each class should have one reason to change. With switch statements, the VendingMachine class changes whenever ANY state's logic changes. With the State pattern, each state class has one reason to change — its own rules. too — the machine class changes whenever ANY state's rules change."

"Wait — the behavior DEPENDS on state. Each state is its own complete behavior set. IdleState knows what to do with coins (accept them). DispensingState knows what to do with coins (reject them). Each state is a class that implements all the methods. That's literally the State pattern."

"The machine just holds a reference to its current state and delegates everything. When the state changes, we swap the object. The machine code itself never changes — only which state object it's pointing to."

The State Machine

Every vending machine has exactly four modes. Here's how they connect — each arrow is a user action or system event that causes a transition:

Full Purchase Sequence

States Block Invalid Operations

enum MachineState { Idle, HasMoney, Dispensing, OutOfService }

public void InsertCoin(decimal amount)
{
    switch (_state)
    {
        case MachineState.Idle:
            _balance += amount;
            _state = MachineState.HasMoney;
            break;
        case MachineState.HasMoney:
            _balance += amount;
            break;
        case MachineState.Dispensing:
            Console.WriteLine("Please wait...");
            break;
        case MachineState.OutOfService:
            Console.WriteLine("Machine is out of service");
            break;
    }
}
// Now repeat this switch in SelectProduct(), Cancel(), Dispense()...
// 4 states × 4 methods = 16 switch branches. Add one state = edit 4 methods.

private bool _isIdle = true;
private bool _hasMoney = false;
private bool _isDispensing = false;
private bool _isOutOfService = false;

public void InsertCoin(decimal amount)
{
    if (_isOutOfService) { Console.WriteLine("Out of service"); return; }
    if (_isDispensing) { Console.WriteLine("Please wait..."); return; }
    _balance += amount;
    _isIdle = false;
    _hasMoney = true;
}
// Problem: what if _isIdle AND _hasMoney are BOTH true?
// That's an impossible state, but the compiler can't prevent it.
// Booleans can't express "exactly one of these is true."

// Each state is a CLASS that knows its own rules.
// The machine just delegates to the current state.
machine.State.InsertMoney(machine, amount);

// IdleState.InsertMoney → accept, transition to HasMoney
// HasMoneyState.InsertMoney → accept, stay in HasMoney
// DispensingState.InsertMoney → reject (motor is running)
// OutOfServiceState.InsertMoney → reject (out of service)

// Add "Maintenance" mode?
// 1. Create MaintenanceState.cs (new file)
// 2. Done. Zero changes to existing states.

Enum+Switch vs. State Pattern

Here's the State pattern applied to our vending machine. Each state is its own class with all four methods. The machine delegatesDelegation means passing responsibility to another object. Instead of the machine deciding what to do with a switch, it says "hey current state, YOU handle this." The machine doesn't know or care which state it's in — it just forwards the call. every action to its current state, and each method returns the next state — a state transitionThe act of moving from one state to another. Returning new HasMoneyState() from IdleState.InsertMoney() means "after this action, the machine is now in HasMoney mode." Returning this means "stay in the current state." — to move to.

/// Every state must implement these four operations.
/// Each method returns the NEXT state to transition to.
/// If the operation isn't allowed, return 'this' (stay put).
public interface IVendingState
{
    IVendingState InsertMoney(VendingMachine machine, decimal amount);
    IVendingState SelectProduct(VendingMachine machine, string slotCode);
    IVendingState DispenseProduct(VendingMachine machine);
    IVendingState Cancel(VendingMachine machine);
}

/// Idle: the machine is waiting for a customer.
/// Only InsertMoney makes sense here — everything else is a no-op.
public sealed class IdleState : IVendingState
{
    public IVendingState InsertMoney(VendingMachine machine, decimal amount)
    {
        machine.AddBalance(amount);
        return new HasMoneyState();  // Transition: Idle → HasMoney
    }

    public IVendingState SelectProduct(VendingMachine m, string code)
        => this;  // Can't select without money — stay Idle

    public IVendingState DispenseProduct(VendingMachine m)
        => this;  // Nothing to dispense — stay Idle

    public IVendingState Cancel(VendingMachine m)
        => this;  // Nothing to cancel — stay Idle
}

/// HasMoney: customer has inserted coins, waiting for selection.
/// InsertMoney adds more. SelectProduct checks and transitions. Cancel refunds.
public sealed class HasMoneyState : IVendingState
{
    public IVendingState InsertMoney(VendingMachine machine, decimal amount)
    {
        machine.AddBalance(amount);
        return this;  // Stay in HasMoney — balance increases
    }

    public IVendingState SelectProduct(VendingMachine machine, string slotCode)
    {
        var slot = machine.GetSlot(slotCode);
        if (slot is null || !slot.HasStock)
            return this;  // Invalid or out of stock — stay HasMoney
        if (machine.Balance < slot.Product.Price)
            return this;  // Not enough money — stay HasMoney

        machine.SetSelectedSlot(slot);
        return new DispensingState();  // Transition: HasMoney → Dispensing
    }

    public IVendingState DispenseProduct(VendingMachine m)
        => this;  // Can't dispense without selecting — stay HasMoney

    public IVendingState Cancel(VendingMachine machine)
    {
        machine.RefundBalance();
        return new IdleState();  // Transition: HasMoney → Idle (refund)
    }
}

/// Dispensing: the motor is running, product is being delivered.
/// ONLY DispenseProduct (motor completion) is valid. Everything else blocked.
public sealed class DispensingState : IVendingState
{
    public IVendingState InsertMoney(VendingMachine m, decimal amount)
        => this;  // Motor is running — can't accept money

    public IVendingState SelectProduct(VendingMachine m, string code)
        => this;  // Motor is running — can't start new selection

    public IVendingState DispenseProduct(VendingMachine machine)
    {
        var slot = machine.SelectedSlot!;
        slot.Decrement();
        machine.DeductBalance(slot.Product.Price);
        // TODO: calculate change in Level 4
        return new IdleState();  // Transition: Dispensing → Idle
    }

    public IVendingState Cancel(VendingMachine m)
        => this;  // Can't cancel mid-dispense — motor already running
}

/// OutOfService: technician is refilling or performing maintenance.
/// NOTHING is allowed except admin re-enabling the machine.
public sealed class OutOfServiceState : IVendingState
{
    public IVendingState InsertMoney(VendingMachine m, decimal amount)
        => this;  // Machine is out of service

    public IVendingState SelectProduct(VendingMachine m, string code)
        => this;  // Machine is out of service

    public IVendingState DispenseProduct(VendingMachine m)
        => this;  // Machine is out of service

    public IVendingState Cancel(VendingMachine m)
        => this;  // Machine is out of service

    // Admin calls machine.Enable() which sets state to IdleState
}

Growing Diagram — After Level 2

Your inner voice:

"Coins, cards, mobile... What varies? The how of payment — not the what. The vending machine doesn't care HOW it gets paid, just THAT it gets paid. Whether someone inserts quarters, taps a Visa, or waves their phone — the end result is the same: money moves."

"I could use a switch statement... switch(type) { case Coin: ... case Card: ... } But then adding crypto means editing that switch. And the switch would be in multiple places — charge AND refund AND display. That's a mess."

"Wait — same interface, different implementations. That's StrategyThe Strategy pattern defines a family of algorithms (like different payment methods), puts each one in its own class, and makes them interchangeable. The code that USES the strategy doesn't know which one it's talking to — it just calls the interface methods. Adding a new strategy means creating a new class, not editing existing ones.. An IPaymentStrategy with Charge() and Refund(). Each payment method is its own class. The vending machine holds a reference to any strategy and just calls Charge() — it doesn't know or care whether that's coins clanking or bytes flying."

What Would You Do?

Three developers, three approaches to "multiple payment types." Read the dead ends first — understanding why they fail is half the lesson.

public PaymentResult Charge(PaymentType type, decimal amount)
{
    switch (type)
    {
        case PaymentType.Coin:
            if (_insertedCoins < amount)
                return PaymentResult.Fail("Insert more coins");
            _insertedCoins -= amount;
            return PaymentResult.Success(_insertedCoins);

        case PaymentType.Card:
            var auth = CreditCardGateway.Authorize(amount);
            if (!auth.Approved) return PaymentResult.Fail("Card declined");
            return PaymentResult.Success(0);

        case PaymentType.Mobile:
            var tap = NfcService.ProcessTap(amount);
            if (!tap.Ok) return PaymentResult.Fail("Tap failed");
            return PaymentResult.Success(0);

        // Adding crypto? Edit THIS method + Refund() + Display()...
    }
}

public class CoinPayment
{
    protected decimal _inserted;
    public void AcceptCoin(decimal coin) => _inserted += coin;
    public virtual PaymentResult Charge(decimal amount) { ... }
}

// Card inherits from Coin?! Cards don't have "inserted coins"...
public class CardPayment : CoinPayment
{
    // _inserted makes no sense here
    // AcceptCoin() makes no sense for a credit card
    // We'd have to override AND ignore the parent's logic
    public override PaymentResult Charge(decimal amount)
    {
        // Completely different logic — nothing reused from parent
        return CreditCardGateway.Authorize(amount);
    }
}

public interface IPaymentStrategy
{
    PaymentResult Charge(decimal amount);
    PaymentResult Refund(decimal amount);
    string DisplayName { get; }
}

// Machine only knows the interface — not the concrete type
public void ProcessPayment(IPaymentStrategy payment, decimal price)
{
    var result = payment.Charge(price);
    if (!result.IsSuccess)
        Console.WriteLine(result.Error);
    else
        DispenseProduct();
}

// Adding crypto? Just create a new class. Zero changes elsewhere.
machine.ProcessPayment(new CryptoPayment(wallet), 1.50m);

The Solution

The Strategy patternA behavioral design pattern that lets you define a family of algorithms, put each one in a separate class, and make their objects interchangeable. The key insight: the code that USES the algorithm only depends on the interface, so you can swap implementations at runtime without changing the caller. gives each payment method its own class. They all speak the same language — IPaymentStrategy — but each one implements Charge() and Refund() in its own way. Coins track a running balance. Cards call an authorization gateway. Mobile payments talk to an NFC service. The vending machine doesn't care which one it's using.

// Every payment method must be able to do two things:
// 1. Charge the customer a specific amount
// 2. Refund the customer if something goes wrong
public interface IPaymentStrategy
{
    PaymentResult Charge(decimal amount);
    PaymentResult Refund(decimal amount);
    string DisplayName { get; }
}

// The result of any payment operation — success or failure, never ambiguous
public sealed record PaymentResult
{
    public bool IsSuccess { get; }
    public decimal RemainingBalance { get; }
    public string? Error { get; }

    private PaymentResult(bool success, decimal balance, string? error)
        => (IsSuccess, RemainingBalance, Error) = (success, balance, error);

    public static PaymentResult Success(decimal remaining)
        => new(true, remaining, null);

    public static PaymentResult Fail(string error)
        => new(false, 0, error);
}

public sealed class CoinPayment : IPaymentStrategy
{
    private decimal _inserted;

    public string DisplayName => "Coins";

    // Coins are special — you insert them BEFORE selecting a product
    public void AcceptCoin(decimal coinValue)
    {
        if (coinValue <= 0)
            throw new ArgumentException("Coin value must be positive.");
        _inserted += coinValue;
    }

    public decimal InsertedAmount => _inserted;

    public PaymentResult Charge(decimal amount)
    {
        // Have they inserted enough coins?
        if (_inserted < amount)
            return PaymentResult.Fail(
                $"Insert {amount - _inserted:C} more.");

        // Deduct the price — leftover is the customer's change
        _inserted -= amount;
        return PaymentResult.Success(_inserted);
    }

    public PaymentResult Refund(decimal amount)
    {
        // Refunding coins = pushing them back out the slot
        _inserted += amount;
        return PaymentResult.Success(_inserted);
    }
}

public sealed class CardPayment : IPaymentStrategy
{
    private readonly ICardGateway _gateway;
    private string? _lastTransactionId;

    public CardPayment(ICardGateway gateway)
        => _gateway = gateway;

    public string DisplayName => "Credit/Debit Card";

    public PaymentResult Charge(decimal amount)
    {
        // Cards work differently — authorize the exact amount
        var auth = _gateway.Authorize(amount);

        if (!auth.Approved)
            return PaymentResult.Fail(
                $"Card declined: {auth.Reason}");

        // Save the transaction ID so we can refund later
        _lastTransactionId = auth.TransactionId;

        // No "remaining balance" for cards — they pay exact
        return PaymentResult.Success(0);
    }

    public PaymentResult Refund(decimal amount)
    {
        if (_lastTransactionId is null)
            return PaymentResult.Fail("No transaction to refund.");

        var refund = _gateway.Refund(_lastTransactionId, amount);
        return refund.Approved
            ? PaymentResult.Success(0)
            : PaymentResult.Fail($"Refund failed: {refund.Reason}");
    }
}

public sealed class MobilePayment : IPaymentStrategy
{
    private readonly INfcService _nfc;
    private string? _paymentToken;

    public MobilePayment(INfcService nfc)
        => _nfc = nfc;

    public string DisplayName => "Mobile (Apple Pay / Google Pay)";

    public PaymentResult Charge(decimal amount)
    {
        // Mobile payments use NFC tap — different protocol entirely
        var tap = _nfc.RequestPayment(amount);

        if (!tap.Completed)
            return PaymentResult.Fail(
                tap.TimedOut ? "Tap timed out. Try again."
                             : $"Payment failed: {tap.Error}");

        _paymentToken = tap.Token;
        return PaymentResult.Success(0);
    }

    public PaymentResult Refund(decimal amount)
    {
        if (_paymentToken is null)
            return PaymentResult.Fail("No mobile payment to refund.");

        var result = _nfc.RefundPayment(_paymentToken, amount);
        return result.Completed
            ? PaymentResult.Success(0)
            : PaymentResult.Fail($"Refund failed: {result.Error}");
    }
}

Diagrams

Strategy Fan-Out — One Interface, Three Implementations

The vending machine depends on IPaymentStrategy — not on any concrete payment class. This means you can plug in coins, cards, mobile, or any future payment without changing the machine.

Payment Flow — From Customer to Dispensing

Regardless of which payment method the customer chooses, the flow through the vending machine is identical. The machine asks the strategy to charge, checks the result, and either dispenses or shows an error.

Runtime Swap — Same Machine, Different "Battery"

Think of each payment strategy like a battery you plug into the machine. The machine works the same regardless of which battery is installed. Swap in a different one at runtime and everything keeps working.

Growing Diagram — Level 3

Four new pieces join the system: the IPaymentStrategy interface and three concrete implementations. The vending machine now depends on the interface, not on any specific payment type.

Before / After Your Brain

Your inner voice:

"I need a Transaction that captures everything: timestamp, product, amount paid, change given, payment method. And the change problem... I have denominations: $1, $0.25, $0.10, $0.05."

"Greedy approach: use the largest denomination first. $0.75 change = 0×$1 + 3×$0.25. But what if I'm out of quarters? I need to check how many of each denomination I actually HAVE in the machine."

"So I need a CoinInventoryA CoinInventory tracks how many of each denomination the machine currently holds. When the machine gives change, it subtracts from inventory. When a customer inserts coins, it adds to inventory. If the machine runs out of quarters, the change calculator must fall back to dimes and nickels. — a mapping of denomination to count. The ChangeCalculator walks through denominations largest to smallest, takes as many as it needs (up to what's available), and moves to the next denomination. If it can't make exact change... that's a real problem we'll handle in Level 5."

What Would You Do?

Two approaches to the change problem. One pretends coins are just numbers. The other models the physical reality of a coin hopper.

public decimal CalculateChange(decimal paid, decimal price)
{
    return paid - price;  // "Here's 0.75. Figure it out yourself."
}

// Problems:
// 1. Machine has no quarters — can't actually give 3 quarters
// 2. Machine has 100 nickels but this code doesn't know
// 3. Receipt says "Change: $0.75" but... in what coins?
// 4. No inventory tracking = machine can't warn "low on change"

// $0.75 change with only dimes and nickels available:
// Try $1.00 — need 0, skip
// Try $0.25 — need 3, have 0, take 0
// Try $0.10 — need 7, have 10, take 7 → $0.05 left
// Try $0.05 — need 1, have 5, take 1 → done!
// Result: 7 dimes + 1 nickel = 8 coins

The Solution

We need four new pieces: a Denomination type to represent coin types, a CoinInventory to track the machine's cash float, a ChangeCalculator with the greedy algorithm, and a Transaction record to capture every purchase.

public readonly record struct Denomination(string Name, decimal Value);

public static class Denominations
{
    public static readonly Denomination Dollar  = new("Dollar",  1.00m);
    public static readonly Denomination Quarter = new("Quarter", 0.25m);
    public static readonly Denomination Dime    = new("Dime",    0.10m);
    public static readonly Denomination Nickel  = new("Nickel",  0.05m);

    // Greedy order: always try the biggest coin first
    public static readonly Denomination[] All =
        [Dollar, Quarter, Dime, Nickel];
}

public sealed class CoinInventory
{
    private readonly Dictionary<Denomination, int> _coins = new();

    public int CountOf(Denomination denom)
        => _coins.GetValueOrDefault(denom, 0);

    public void Add(Denomination denom, int count)
        => _coins[denom] = CountOf(denom) + count;

    public void Remove(Denomination denom, int count)
    {
        var current = CountOf(denom);
        if (count > current)
            throw new InvalidOperationException(
                $"Can't remove {count} {denom.Name}s — only {current} available.");
        _coins[denom] = current - count;
    }

    public decimal TotalValue =>
        _coins.Sum(kv => kv.Key.Value * kv.Value);
}

public sealed class ChangeCalculator
{
    public ChangeResult Calculate(decimal amount, CoinInventory inventory)
    {
        var coins = new List<(Denomination Denom, int Count)>();
        var remaining = amount;

        foreach (var denom in Denominations.All)
        {
            if (remaining <= 0) break;

            var available = inventory.CountOf(denom);
            var needed = (int)(remaining / denom.Value);
            var used = Math.Min(needed, available);

            if (used > 0)
            {
                coins.Add((denom, used));
                remaining -= used * denom.Value;
                inventory.Remove(denom, used);
            }
        }

        return remaining > 0
            ? ChangeResult.CannotMakeChange(remaining)
            : ChangeResult.Success(coins);
    }
}

public sealed record ChangeResult
{
    public bool IsSuccess { get; }
    public IReadOnlyList<(Denomination Denom, int Count)> Coins { get; }
    public decimal Shortfall { get; }

    private ChangeResult(bool ok, IReadOnlyList<(Denomination, int)> coins, decimal shortfall)
        => (IsSuccess, Coins, Shortfall) = (ok, coins, shortfall);

    public static ChangeResult Success(List<(Denomination, int)> coins)
        => new(true, coins, 0);

    public static ChangeResult CannotMakeChange(decimal shortfall)
        => new(false, Array.Empty<(Denomination, int)>(), shortfall);
}

public sealed record Transaction
{
    public required Guid Id { get; init; }
    public required DateTimeOffset Timestamp { get; init; }
    public required Product Product { get; init; }
    public required string SlotCode { get; init; }
    public required decimal AmountCharged { get; init; }
    public required string PaymentMethod { get; init; }
    public required ChangeResult? Change { get; init; }
}

public sealed record Receipt(Transaction Txn)
{
    public string Format() =>
        $"""
        ================================
          VENDING MACHINE RECEIPT
        ================================
        Date:    {Txn.Timestamp:g}
        Product: {Txn.Product.Name}
        Slot:    {Txn.SlotCode}
        Price:   {Txn.Product.Price:C}
        Paid:    {Txn.AmountCharged:C}
        Change:  {FormatChange()}
        Method:  {Txn.PaymentMethod}
        Txn ID:  {Txn.Id:N}
        ================================
        """;

    private string FormatChange() =>
        Txn.Change is null ? "N/A"
        : string.Join(", ",
            Txn.Change.Coins.Select(c => $"{c.Count}x {c.Denom.Name}"));
}

Diagrams

Transaction Flow — From Insert to Receipt

Every purchase follows this pipeline. The transaction record is created at the end, capturing the complete story.

Change Calculation — Step by Step

The customer needs $0.75 in change, but the machine is out of quarters. Watch how the greedy algorithm falls back to dimes and a nickel.

What the Receipt Looks Like

Growing Diagram — Level 4

Four new types join: CoinInventory, ChangeCalculator, Transaction, and Receipt.

Before / After Your Brain

Your inner voice:

"Let me walk through the What If? categories systematically..."

"Concurrency: Two customers hit 'Buy' on the same last item. Without a lock, both get past the stock check, both try to dispense. One gets the Coke, the other gets nothing but still gets charged. I need lock around the check-and-dispense operation to make it atomicAn atomic operation is one that either happens completely or not at all — nothing can interrupt it halfway through. When you check stock and dispense in one lock, no other thread can sneak in between. Without atomicity, a second customer can pass the stock check right before the first customer takes the last item.."

"Failure: Card declined after we started the flow? Refund and reset to idle. Motor jams and the item gets stuck? Retry once, then refund and flag the slot as out of service. NFC timeout? Same — refund and reset."

"Boundary: Machine can't make change? Check BEFORE dispensing, not after. Machine's coin hopper is full? Reject new coins, suggest card payment."

"I don't want exceptions flying everywhere. I need a clean result type that says 'this worked, here's the result' or 'this failed, here's exactly why.' Something like VendingResult<T>."

What Would You Do?

Three approaches to error handling. One crashes, one is cryptic, and one is just right.

public Product SelectProduct(string slotCode)
{
    var slot = _slots[slotCode]; // KeyNotFoundException if invalid!
    if (slot.Quantity == 0)
        throw new InvalidOperationException("Out of stock");
    if (_balance < slot.Product.Price)
        throw new InvalidOperationException("Insufficient funds");
    // ... dispense ...
}

// Caller needs try-catch everywhere
try { machine.SelectProduct("A3"); }
catch (KeyNotFoundException) { /* invalid slot */ }
catch (InvalidOperationException ex) { /* which one?! */ }

public Product? SelectProduct(string slotCode)
{
    if (!_slots.ContainsKey(slotCode)) return null;  // Invalid slot
    if (_slots[slotCode].Quantity == 0) return null;  // Out of stock
    if (_balance < _slots[slotCode].Product.Price) return null; // No $
    // ... dispense ...
    return product;
}

// Caller: "it returned null. Was it invalid? Out of stock? No money?"
// Nobody knows. The null is silent.

public VendingResult<Receipt> Purchase(string slotCode)
{
    if (!_slots.ContainsKey(slotCode))
        return VendingResult<Receipt>.Fail("Invalid slot code.");

    var slot = _slots[slotCode];
    if (slot.Quantity == 0)
        return VendingResult<Receipt>.Fail($"{slot.Product.Name} is sold out.");

    if (_balance < slot.Product.Price)
        return VendingResult<Receipt>.Fail(
            $"Insert {slot.Product.Price - _balance:C} more.");

    // All checks passed — safe to dispense
    var receipt = DispenseAndRecord(slot);
    return VendingResult<Receipt>.Ok(receipt);
}

// Caller: crystal clear
var result = machine.Purchase("A3");
if (result.IsSuccess) Show(result.Value);
else ShowError(result.Error); // Knows exactly what's wrong

The Solution

We need VendingResult<T> as the universal return type, plus validation guards and a lock for concurrency safety.

public sealed record VendingResult<T>
{
    public bool IsSuccess { get; }
    public T? Value { get; }
    public string? Error { get; }

    private VendingResult(bool success, T? value, string? error)
        => (IsSuccess, Value, Error) = (success, value, error);

    public static VendingResult<T> Ok(T value) => new(true, value, null);
    public static VendingResult<T> Fail(string error) => new(false, default, error);

    // Convenience: map success to a new type
    public VendingResult<TNext> Then<TNext>(Func<T, VendingResult<TNext>> next)
        => IsSuccess ? next(Value!) : VendingResult<TNext>.Fail(Error!);
}

private readonly object _purchaseLock = new();

public VendingResult<Receipt> Purchase(string slotCode, IPaymentStrategy payment)
{
    // Lock the entire check-and-dispense operation
    lock (_purchaseLock)
    {
        // Gate 1: Valid slot?
        if (!_slots.TryGetValue(slotCode, out var slot))
            return VendingResult<Receipt>.Fail("Invalid slot code.");

        // Gate 2: In stock?
        if (slot.Quantity == 0)
            return VendingResult<Receipt>.Fail(
                $"{slot.Product.Name} is sold out.");

        // Gate 3: Can we make change? (check BEFORE charging)
        var changeNeeded = payment is CoinPayment cp
            ? cp.InsertedAmount - slot.Product.Price : 0m;
        if (changeNeeded > 0)
        {
            var changeCheck = _changeCalc.CanMakeChange(
                changeNeeded, _coinInventory);
            if (!changeCheck)
                return VendingResult<Receipt>.Fail(
                    "Machine cannot make exact change. Try card payment.");
        }

        // Gate 4: Charge the customer
        var payResult = payment.Charge(slot.Product.Price);
        if (!payResult.IsSuccess)
            return VendingResult<Receipt>.Fail(payResult.Error!);

        // Gate 5: Dispense (with stuck-item retry)
        var dispensed = slot.TryDispense();
        if (!dispensed)
        {
            payment.Refund(slot.Product.Price);
            return VendingResult<Receipt>.Fail(
                "Item stuck. Refund issued. Please try again.");
        }

        // All gates passed — log transaction
        var txn = CreateTransaction(slot, payment, changeNeeded);
        return VendingResult<Receipt>.Ok(new Receipt(txn));
    }
}

public sealed class Slot
{
    private const int MaxDispenseRetries = 2;

    public bool TryDispense()
    {
        for (int attempt = 1; attempt <= MaxDispenseRetries; attempt++)
        {
            var success = _motor.Activate(); // Physical motor push

            if (success)
            {
                Quantity--;
                return true;
            }

            // Item stuck — wait briefly, try again
            Thread.Sleep(500); // Brief pause before retry
        }

        // All retries failed — item is truly stuck
        IsOutOfService = true;
        _notifier?.NotifyTechnician(
            $"Slot {Code}: item stuck after {MaxDispenseRetries} retries");
        return false;
    }
}

Diagrams

The What If? Framework — Four Quadrants

Every production bug falls into one of these four categories. Ask these questions BEFORE writing code, and you'll catch edge cases before they catch you at 2 AM.

Stuck Item Recovery Flow

When the dispenser motor can't push the item out, the machine doesn't just give up. It retries, and if that fails, it refunds the customer and notifies a technician.

Validation Gate Chain — Every Step Can Reject

The purchase flow is a chain of gates. Each gate can reject the request with a clear error. Only when ALL gates pass does the item actually dispense.

Growing Diagram — Level 5

Before / After Your Brain

Your inner voice:

"The core problem is that the machine creates its own collaborators. I need to flip this: instead of the machine creating them, they get passed in. That's Dependency InjectionDependency Injection means giving an object the things it needs from the outside instead of letting it create them internally. Think of a restaurant: the chef doesn't grow the vegetables — they're delivered (injected). This makes the chef testable: swap in plastic vegetables (fakes) and verify the chef follows the recipe correctly.."

"For card payments, I already have ICardGateway — I just need to inject it. For NFC, same thing with INfcService. For the coin inventory, I pass a pre-loaded one in the constructor. For time, .NET 8 has TimeProvider built in — tests use FakeTimeProvider."

"The machine itself should sit behind an IVendingMachine interface too. That way, if someone builds a UI controller that talks to the machine, they can test the controller with a fake machine."

What Would You Do?

Two developers, two approaches to making the card gateway testable.

public sealed class CardPayment : IPaymentStrategy
{
    // Gateway created internally — can't swap it!
    private readonly CardGateway _gateway = new CardGateway();

    public PaymentResult Charge(decimal amount)
        => _gateway.Authorize(amount); // Hits the real network
}

public sealed class CardPayment(ICardGateway gateway) : IPaymentStrategy
{
    // Gateway INJECTED — fully controllable from outside
    public PaymentResult Charge(decimal amount)
        => gateway.Authorize(amount);
}

// In tests:
var fakeGateway = new FakeCardGateway(approved: false, reason: "Declined");
var payment = new CardPayment(fakeGateway);
var result = payment.Charge(1.50m);
Assert.False(result.IsSuccess);
Assert.Equal("Card declined: Declined", result.Error);

The Solution — Injectable Everything

The idea is simple: every "thing" your machine talks to becomes a constructor parameter behind an interface. In production, you pass real implementations. In tests, you pass fakes.

// The machine itself becomes an interface
public interface IVendingMachine
{
    VendingResult<Receipt> Purchase(string slotCode, IPaymentStrategy payment);
    VendingResult<decimal> InsertCoin(decimal amount);
    IReadOnlyList<SlotInfo> GetAvailableProducts();
}

// External card processor
public interface ICardGateway
{
    AuthResult Authorize(decimal amount);
    AuthResult Refund(string transactionId, decimal amount);
}

// NFC/mobile payment processor
public interface INfcService
{
    NfcResult RequestPayment(decimal amount);
    NfcResult RefundPayment(string token, decimal amount);
}

// Time provider (use .NET 8 built-in TimeProvider)
// Production: TimeProvider.System
// Tests: FakeTimeProvider with frozen clock

// Production wiring — real implementations
var services = new ServiceCollection();
services.AddSingleton<ICardGateway, StripeCardGateway>();
services.AddSingleton<INfcService, ApplePayNfcService>();
services.AddSingleton<TimeProvider>(TimeProvider.System);
services.AddSingleton<CoinInventory>(sp =>
{
    var inv = new CoinInventory();
    inv.Add(Denominations.Quarter, 40);
    inv.Add(Denominations.Dime, 50);
    inv.Add(Denominations.Nickel, 30);
    inv.Add(Denominations.Dollar, 10);
    return inv;
});
services.AddSingleton<ChangeCalculator>();
services.AddSingleton<IVendingMachine, VendingMachine>();

var provider = services.BuildServiceProvider();
var machine = provider.GetRequiredService<IVendingMachine>();

[Fact]
public void Only_nickels_returns_15_nickels_for_75_cents_change()
{
    // Arrange: inventory with ONLY nickels
    var inventory = new CoinInventory();
    inventory.Add(Denominations.Nickel, 20);
    var calc = new ChangeCalculator();

    // Act
    var result = calc.Calculate(0.75m, inventory);

    // Assert
    Assert.True(result.IsSuccess);
    Assert.Single(result.Coins); // Only one denomination used
    Assert.Equal("Nickel", result.Coins[0].Denom.Name);
    Assert.Equal(15, result.Coins[0].Count);
}

[Fact]
public void Card_declined_returns_failure_and_does_not_dispense()
{
    // Arrange: fake gateway that always declines
    var fakeGateway = new FakeCardGateway(approved: false, reason: "Insufficient funds");
    var payment = new CardPayment(fakeGateway);
    var machine = CreateTestMachine(stockedWith: "Coke", price: 1.50m);

    // Act
    var result = machine.Purchase("A1", payment);

    // Assert
    Assert.False(result.IsSuccess);
    Assert.Contains("Insufficient funds", result.Error);
    Assert.Equal(1, machine.GetSlot("A1").Quantity); // Nothing dispensed!
}

[Fact]
public void Cannot_make_change_rejects_before_charging()
{
    // Arrange: empty coin inventory
    var emptyInventory = new CoinInventory();
    var machine = CreateTestMachine(coinInventory: emptyInventory);
    var coins = new CoinPayment();
    coins.AcceptCoin(2.00m); // Paying $2 for a $1.25 item = $0.75 change

    // Act
    var result = machine.Purchase("A1", coins);

    // Assert: rejected BEFORE charging — coins returned
    Assert.False(result.IsSuccess);
    Assert.Contains("cannot make exact change", result.Error);
}

Diagrams

Dependency Injection Graph

The vending machine depends on interfaces (dashed boxes). In production, real implementations plug in. In tests, fakes plug in. The machine never knows the difference.

Test Setup: Fake Inventory with Only Nickels

Growing Diagram — Level 6

Before / After Your Brain

Your inner voice:

"500 machines... I need a FleetManager that tracks them all by ID. Each machine already has its own state and inventory from previous levels, so they're naturally isolated."

"But notifications are the key. When Machine #47 sells the last Coke, the dashboard needs to update, the warehouse needs to schedule a restock, and the analytics system needs to log it. The machine should NOT know about any of these systems — that would be tight couplingTight coupling means two components know too much about each other. If the machine directly calls dashboard.Update(), then adding a warehouse notifier means editing the machine class. Loose coupling means the machine just says "something happened" and anyone who cares can listen.."

"Observer pattern: the machine emits events, and any number of listeners subscribe. Adding analytics later? One line: Subscribe(new AnalyticsObserver()). No machine code changes. This is also the bridge to HLDHigh-Level Design — the architecture of distributed systems. While LLD focuses on classes and patterns within a single application, HLD deals with how services communicate across networks. The Observer pattern in LLD maps directly to message queues and event buses in HLD. — in a distributed system, these events become messages on a message queue."

What Would You Do?

Three approaches to getting information from 500 machines to a central dashboard.

// Machine knows about everything
private readonly Dashboard _dashboard;
private readonly Warehouse _warehouse;

public void AfterSale(Transaction txn)
{
    _dashboard.Update(MachineId, txn);    // Tight coupling
    _warehouse.CheckRestock(MachineId);   // More coupling
    // Adding analytics? Edit THIS class again...
}

// Dashboard checks 500 machines every 5 seconds
while (true)
{
    foreach (var machine in fleet)  // 500 iterations
    {
        var state = machine.GetStatus();
        if (state != lastKnown[machine.Id])
            UpdateDashboard(machine.Id, state);
    }
    await Task.Delay(5000);  // 500 wasted checks most of the time
}

public interface IMachineObserver
{
    void OnSaleCompleted(string machineId, Transaction txn);
    void OnLowStock(string machineId, string productName, int remaining);
    void OnError(string machineId, string error);
}

// Machine just announces — doesn't know who listens
public void Subscribe(IMachineObserver observer)
    => _observers.Add(observer);

// One line to add a new listener — zero machine changes
fleet.Subscribe(new DashboardObserver());
fleet.Subscribe(new WarehouseObserver(threshold: 3));
fleet.Subscribe(new AnalyticsObserver());
fleet.Subscribe(new TemperatureAlertObserver());

The Solution — FleetManager + Observer + Events

We add three new pieces: MachineEvent records to describe what happened, an IMachineObserver interface for listeners, and a FleetManager to orchestrate the fleet.

// Base event — every event knows which machine and when
public abstract record MachineEvent(
    string MachineId,
    DateTimeOffset Timestamp);

// A sale was completed
public sealed record SaleEvent(
    string MachineId, DateTimeOffset Timestamp,
    Transaction Transaction) : MachineEvent(MachineId, Timestamp);

// Stock is running low
public sealed record LowStockEvent(
    string MachineId, DateTimeOffset Timestamp,
    string ProductName, int Remaining) : MachineEvent(MachineId, Timestamp);

// Something went wrong
public sealed record ErrorEvent(
    string MachineId, DateTimeOffset Timestamp,
    string ErrorType, string Message) : MachineEvent(MachineId, Timestamp);

// Observer interface — implement this to listen for events
public interface IMachineObserver
{
    void OnEvent(MachineEvent machineEvent);
}

public sealed class FleetManager
{
    private readonly ConcurrentDictionary<string, IVendingMachine> _machines = new();
    private readonly List<IMachineObserver> _observers = [];
    private const int LowStockThreshold = 3;

    public string RegisterMachine(IVendingMachine machine)
    {
        var id = $"VM-{_machines.Count + 1:D4}"; // VM-0001, VM-0002, ...
        _machines[id] = machine;
        return id;
    }

    public void Subscribe(IMachineObserver observer)
        => _observers.Add(observer);

    // Called after each purchase — emit events to all observers
    public void OnPurchaseCompleted(string machineId, Transaction txn)
    {
        var timestamp = TimeProvider.System.GetUtcNow();

        // Sale event
        Emit(new SaleEvent(machineId, timestamp, txn));

        // Check if stock is low
        var machine = _machines[machineId];
        foreach (var slot in machine.GetAvailableProducts())
        {
            if (slot.Quantity > 0 && slot.Quantity <= LowStockThreshold)
                Emit(new LowStockEvent(
                    machineId, timestamp, slot.ProductName, slot.Quantity));
        }
    }

    private void Emit(MachineEvent evt)
    {
        foreach (var observer in _observers)
            observer.OnEvent(evt);
    }
}

// Dashboard: updates the central monitoring screen
public sealed class DashboardObserver : IMachineObserver
{
    public void OnEvent(MachineEvent evt)
    {
        switch (evt)
        {
            case SaleEvent sale:
                UpdateRevenue(sale.MachineId, sale.Transaction.AmountCharged);
                break;
            case ErrorEvent error:
                ShowAlert(error.MachineId, error.Message);
                break;
        }
    }
}

// Warehouse: triggers restocking when inventory is low
public sealed class WarehouseObserver : IMachineObserver
{
    public void OnEvent(MachineEvent evt)
    {
        if (evt is LowStockEvent low)
        {
            Console.WriteLine(
                $"[WAREHOUSE] Restock {low.ProductName} at {low.MachineId}" +
                $" — only {low.Remaining} left!");
            ScheduleRestock(low.MachineId, low.ProductName);
        }
    }
}

// Analytics: logs everything for reporting
public sealed class AnalyticsObserver : IMachineObserver
{
    public void OnEvent(MachineEvent evt)
        => _eventStore.Append(evt); // Immutable event log
}

Diagrams

Fleet Architecture — 500 Machines, One Dashboard

Observer Flow — One Event, Many Reactions

Growing Diagram — Level 7 (Complete System)

Before / After Your Brain

You've built this vending machine one constraint at a time across seven levels. Now it's time to see the whole thing assembled in one place. Every file below is the final, production-ready version — incorporating every pattern and refinement we discovered along the way.

Before we dive into the code, here's a bird's-eye view of every type in the system, color-coded by the level that introduced it. Gray types came first (Level 0), green from Level 1, blue from Level 2 (State), and so on all the way to yellow for Level 7 (Observer). Notice how the system grew organically — each type was forced into existenceNo type was planned in advance. Each one appeared because a real constraint made the previous design painful. Product appeared when we needed multiple items. IVendingState appeared when boolean flags couldn't handle 4 modes. This is emergent design — letting constraints drive architecture. by a real constraint, not by upfront planning.

Now let's see the actual code. Each file is organized by responsibility — models in one place, states in another, strategies in a third. Click through the tabs to read each file. Every line is annotated with a // Level N comment so you can trace which constraint introduced that code.

namespace VendingMachine.Models;

// ─── Product ──────────────────────────────────────────
// Level 1 — A product is pure data: a name and a price.
// Records give us value equality and immutability for free.
public sealed record Product(string Name, decimal Price);

// ─── Slot ─────────────────────────────────────────────
// Level 1 — A physical slot in the machine holds a product
// and tracks how many units are left. The slot code (like
// "A1", "B3") is how customers identify what they want.
public sealed class Slot
{
    public string Code { get; }                  // Level 1 — "A1", "B3"
    public Product Product { get; }              // Level 1 — what this slot sells
    public int Quantity { get; private set; }     // Level 1 — how many left

    public Slot(string code, Product product, int quantity)
    {
        Code = code;
        Product = product;
        Quantity = quantity;
    }

    public bool IsAvailable => Quantity > 0;     // Level 5 — stock check

    public void Dispense()                        // Level 1 — reduce inventory
    {
        if (Quantity <= 0)                        // Level 5 — guard
            throw new InvalidOperationException($"Slot {Code} is empty.");
        Quantity--;
    }

    public void Restock(int amount) => Quantity += amount; // Level 7 — fleet ops
}

// ─── Denomination ─────────────────────────────────────
// Level 4 — The physical coins the machine can hold.
// Modeled as an enum because denominations are fixed
// categories, not objects with behavior.
public enum Denomination
{
    Penny   = 1,
    Nickel  = 5,
    Dime    = 10,
    Quarter = 25,
    Dollar  = 100
}

// ─── CoinInventory ────────────────────────────────────
// Level 4 — Tracks REAL coins inside the machine.
// This matters because change isn't an abstract number;
// the machine must have physical coins to return.
public sealed class CoinInventory
{
    private readonly Dictionary<Denomination, int> _coins = new()
    {
        [Denomination.Penny]   = 100,             // Level 4 — default stock
        [Denomination.Nickel]  = 40,
        [Denomination.Dime]    = 40,
        [Denomination.Quarter] = 40,
        [Denomination.Dollar]  = 20
    };

    public void Add(Denomination coin, int count = 1)   // Level 4
        => _coins[coin] += count;

    public bool TryRemove(Denomination coin, int count = 1) // Level 4
    {
        if (_coins[coin] < count) return false;
        _coins[coin] -= count;
        return true;
    }

    public int CountOf(Denomination coin) => _coins[coin]; // Level 5 — diagnostics
}

// ─── VendingResult<T> ─────────────────────────────────
// Level 5 — Instead of throwing exceptions for expected
// failures (out of stock, not enough money), we return a
// result object. The caller checks Success, never catches.
public sealed record VendingResult<T>(
    bool Success, T? Value, string? Error)
{
    public static VendingResult<T> Ok(T value)
        => new(true, value, null);
    public static VendingResult<T> Fail(string error)
        => new(false, default, error);
}

// ─── Transaction ──────────────────────────────────────
// Level 4 — An immutable snapshot of a completed purchase.
// Records are perfect here: once a transaction happens,
// it should never be modified.
public sealed record Transaction(
    string TransactionId,                         // Level 4 — unique ID
    string SlotCode,                              // Level 1 — which slot
    string ProductName,                           // Level 1 — what was bought
    decimal AmountPaid,                           // Level 3 — how much inserted
    decimal ProductPrice,                         // Level 1 — item cost
    decimal ChangeGiven,                          // Level 4 — difference returned
    DateTimeOffset Timestamp);                    // Level 4 — when it happened

// ─── Receipt ──────────────────────────────────────────
// Level 4 — Customer-facing summary of the transaction.
public sealed record Receipt(
    Transaction Transaction,                      // Level 4 — full details
    IReadOnlyList<(Denomination Coin, int Count)> ChangeBreakdown); // Level 4

// ─── PaymentResult ────────────────────────────────────
// Level 4 — Returned by payment strategies to tell the
// machine whether the payment went through and how much
// was actually charged.
public sealed record PaymentResult(
    bool Accepted,                                // Level 3 — success/fail
    decimal AmountCharged,                        // Level 3 — how much collected
    string? DeclineReason);                       // Level 5 — why it failed

namespace VendingMachine.States;

using VendingMachine.Models;

// ─── IVendingState ────────────────────────────────────
// Level 2 — The contract every state must follow.
// The machine delegates ALL behavior to the current state.
// When you call machine.InsertMoney(), it's really calling
// _currentState.InsertMoney(this).
public interface IVendingState
{
    VendingResult<string> InsertMoney(VendingMachine machine, decimal amount);
    VendingResult<Receipt> SelectProduct(VendingMachine machine, string slotCode);
    VendingResult<decimal> ReturnMoney(VendingMachine machine);
    string StateName { get; }                     // Level 7 — for observers
}

// ─── IdleState ────────────────────────────────────────
// Level 2 — Machine is waiting. Only InsertMoney makes sense.
public sealed class IdleState : IVendingState
{
    public string StateName => "Idle";

    public VendingResult<string> InsertMoney(
        VendingMachine machine, decimal amount)
    {
        if (amount <= 0)                          // Level 5 — validation
            return VendingResult<string>.Fail("Amount must be positive.");

        machine.CurrentBalance += amount;         // Level 2
        machine.TransitionTo(new HasMoneyState()); // Level 2 — state change
        return VendingResult<string>.Ok(
            $"Inserted {amount:C}. Balance: {machine.CurrentBalance:C}");
    }

    public VendingResult<Receipt> SelectProduct(
        VendingMachine machine, string slotCode)
    {
        return VendingResult<Receipt>.Fail(       // Level 2 — rejected
            "Please insert money first.");
    }

    public VendingResult<decimal> ReturnMoney(VendingMachine machine)
    {
        return VendingResult<decimal>.Fail(        // Level 2 — nothing to return
            "No money inserted.");
    }
}

// ─── HasMoneyState ────────────────────────────────────
// Level 2 — Customer has inserted money. Now they can
// select a product, insert more, or ask for their money back.
public sealed class HasMoneyState : IVendingState
{
    public string StateName => "HasMoney";

    public VendingResult<string> InsertMoney(
        VendingMachine machine, decimal amount)
    {
        if (amount <= 0)                          // Level 5
            return VendingResult<string>.Fail("Amount must be positive.");

        machine.CurrentBalance += amount;         // Level 2 — add more
        return VendingResult<string>.Ok(
            $"Added {amount:C}. Balance: {machine.CurrentBalance:C}");
    }

    public VendingResult<Receipt> SelectProduct(
        VendingMachine machine, string slotCode)
    {
        // Level 5 — validate slot exists
        if (string.IsNullOrWhiteSpace(slotCode))
            return VendingResult<Receipt>.Fail("Slot code is required.");

        var slot = machine.FindSlot(slotCode);    // Level 1
        if (slot is null)
            return VendingResult<Receipt>.Fail($"No slot '{slotCode}' found.");

        // Level 5 — validate stock
        if (!slot.IsAvailable)
            return VendingResult<Receipt>.Fail($"{slot.Product.Name} is sold out.");

        // Level 5 — validate balance
        if (machine.CurrentBalance < slot.Product.Price)
            return VendingResult<Receipt>.Fail(
                $"Insufficient funds. Need {slot.Product.Price:C}, " +
                $"have {machine.CurrentBalance:C}.");

        // Level 2 — transition to dispensing
        machine.TransitionTo(new DispensingState());
        return machine.DispenseProduct(slot);     // Level 4 — actual dispense
    }

    public VendingResult<decimal> ReturnMoney(VendingMachine machine)
    {
        var amount = machine.CurrentBalance;      // Level 2
        machine.CurrentBalance = 0;
        machine.TransitionTo(new IdleState());    // Level 2 — back to idle
        return VendingResult<decimal>.Ok(amount);
    }
}

// ─── DispensingState ──────────────────────────────────
// Level 2 — Machine is physically delivering the product.
// ALL operations are rejected during dispensing.
public sealed class DispensingState : IVendingState
{
    public string StateName => "Dispensing";

    public VendingResult<string> InsertMoney(
        VendingMachine machine, decimal amount)
        => VendingResult<string>.Fail("Please wait, dispensing in progress.");

    public VendingResult<Receipt> SelectProduct(
        VendingMachine machine, string slotCode)
        => VendingResult<Receipt>.Fail("Please wait, dispensing in progress.");

    public VendingResult<decimal> ReturnMoney(VendingMachine machine)
        => VendingResult<decimal>.Fail("Please wait, dispensing in progress.");
}

// ─── OutOfServiceState ────────────────────────────────
// Level 2 — Machine is broken or being maintained.
// This is the Null Object pattern: every method returns a
// polite rejection instead of throwing an exception.
public sealed class OutOfServiceState : IVendingState
{
    public string StateName => "OutOfService";

    public VendingResult<string> InsertMoney(
        VendingMachine machine, decimal amount)
        => VendingResult<string>.Fail("Machine is out of service.");

    public VendingResult<Receipt> SelectProduct(
        VendingMachine machine, string slotCode)
        => VendingResult<Receipt>.Fail("Machine is out of service.");

    public VendingResult<decimal> ReturnMoney(VendingMachine machine)
        => VendingResult<decimal>.Fail("Machine is out of service.");
}

namespace VendingMachine.Payments;

using VendingMachine.Models;

// ─── IPaymentStrategy ─────────────────────────────────
// Level 3 — Every payment method must implement this.
// The machine doesn't care HOW you pay, only that the
// strategy returns a PaymentResult saying yes or no.
public interface IPaymentStrategy
{
    PaymentResult Process(decimal amount);        // Level 3
    string MethodName { get; }                    // Level 7 — for receipts
}

// ─── CoinPayment ──────────────────────────────────────
// Level 3 — Physical coins inserted into the machine.
// Coins are already in the balance, so this always succeeds.
public sealed class CoinPayment : IPaymentStrategy
{
    public string MethodName => "Coin";

    public PaymentResult Process(decimal amount)
    {
        // Level 3 — Coins were pre-inserted, always accepted
        return new PaymentResult(
            Accepted: true,
            AmountCharged: amount,
            DeclineReason: null);
    }
}

// ─── CardPayment ──────────────────────────────────────
// Level 3 — Credit/debit card via the payment gateway.
// In production, this talks to a real payment processor.
// Level 6 — The gateway is injected (not hardcoded).
public sealed class CardPayment : IPaymentStrategy
{
    private readonly IPaymentGateway _gateway;    // Level 6 — DI

    public CardPayment(IPaymentGateway gateway)
        => _gateway = gateway;

    public string MethodName => "Card";

    public PaymentResult Process(decimal amount)
    {
        // Level 6 — delegate to injected gateway
        var success = _gateway.Charge(amount);    // Level 3
        return new PaymentResult(
            Accepted: success,
            AmountCharged: success ? amount : 0m,
            DeclineReason: success ? null : "Card declined.");
    }
}

// ─── MobilePayment ────────────────────────────────────
// Level 3 — NFC / QR code / Apple Pay / Google Pay.
// Same interface, completely different implementation.
public sealed class MobilePayment : IPaymentStrategy
{
    private readonly IPaymentGateway _gateway;    // Level 6

    public MobilePayment(IPaymentGateway gateway)
        => _gateway = gateway;

    public string MethodName => "Mobile";

    public PaymentResult Process(decimal amount)
    {
        var success = _gateway.Charge(amount);    // Level 3
        return new PaymentResult(
            Accepted: success,
            AmountCharged: success ? amount : 0m,
            DeclineReason: success ? null : "Mobile payment failed.");
    }
}

// ─── IPaymentGateway ──────────────────────────────────
// Level 6 — Abstraction for the actual payment processor.
// In tests, you inject a mock. In production, the real API.
public interface IPaymentGateway
{
    bool Charge(decimal amount);
}

namespace VendingMachine;

using VendingMachine.Models;
using VendingMachine.States;
using VendingMachine.Payments;

// Level 0-7 — The machine itself. Delegates almost
// everything to the current state, payment strategy,
// and change calculator. It's the GLUE, not the logic.
public sealed class VendingMachine
{
    // ─── Dependencies (injected) ──────────────────────
    private readonly Dictionary<string, Slot> _slots;         // Level 1
    private readonly IChangeCalculator _changeCalc;            // Level 6
    private readonly CoinInventory _coinInventory;             // Level 4
    private readonly List<IMachineObserver> _observers = [];   // Level 7
    private readonly object _lock = new();                     // Level 5

    // ─── State ────────────────────────────────────────
    private IVendingState _currentState;                       // Level 2
    public decimal CurrentBalance { get; set; }                // Level 2
    public string CurrentStateName => _currentState.StateName; // Level 7

    public VendingMachine(
        IEnumerable<Slot> slots,                               // Level 1
        IChangeCalculator changeCalculator,                    // Level 6
        CoinInventory? coinInventory = null)                   // Level 4
    {
        _slots = slots.ToDictionary(s => s.Code);            // Level 1
        _changeCalc = changeCalculator;                        // Level 6
        _coinInventory = coinInventory ?? new CoinInventory(); // Level 4
        _currentState = new IdleState();                       // Level 2
    }

    // ─── Public API (delegates to current state) ──────
    public VendingResult<string> InsertMoney(decimal amount)
    {
        lock (_lock)                                           // Level 5
        {
            var result = _currentState.InsertMoney(this, amount);
            if (result.Success)
                Notify(new MachineEvent("MoneyInserted",       // Level 7
                    $"Inserted {amount:C}"));
            return result;
        }
    }

    public VendingResult<Receipt> SelectProduct(string slotCode)
    {
        lock (_lock)                                           // Level 5
        {
            return _currentState.SelectProduct(this, slotCode);
        }
    }

    public VendingResult<decimal> ReturnMoney()
    {
        lock (_lock)                                           // Level 5
        {
            var result = _currentState.ReturnMoney(this);
            if (result.Success)
                Notify(new MachineEvent("MoneyReturned",       // Level 7
                    $"Returned {result.Value:C}"));
            return result;
        }
    }

    // ─── Internal helpers (used by states) ────────────
    public Slot? FindSlot(string code)                         // Level 1
        => _slots.GetValueOrDefault(code);

    public void TransitionTo(IVendingState newState)           // Level 2
    {
        var oldName = _currentState.StateName;
        _currentState = newState;
        Notify(new MachineEvent("StateChanged",                // Level 7
            $"{oldName} → {newState.StateName}"));
    }

    public VendingResult<Receipt> DispenseProduct(Slot slot)   // Level 4
    {
        // Level 4 — Calculate change
        var change = CurrentBalance - slot.Product.Price;
        var breakdown = _changeCalc.Calculate(change, _coinInventory);

        // Level 5 — Can we actually make change?
        if (breakdown is null)
        {
            TransitionTo(new HasMoneyState());
            return VendingResult<Receipt>.Fail(
                "Cannot make exact change. Please use a different amount.");
        }

        // Level 1 — Dispense the item
        slot.Dispense();

        // Level 4 — Build transaction + receipt
        var txn = new Transaction(
            TransactionId: Guid.NewGuid().ToString("N")[..8],
            SlotCode: slot.Code,
            ProductName: slot.Product.Name,
            AmountPaid: CurrentBalance,
            ProductPrice: slot.Product.Price,
            ChangeGiven: change,
            Timestamp: DateTimeOffset.UtcNow);

        var receipt = new Receipt(txn, breakdown);

        // Level 4 — Remove coins from inventory for change
        foreach (var (coin, count) in breakdown)
            _coinInventory.TryRemove(coin, count);

        // Level 2 — Reset
        CurrentBalance = 0;
        TransitionTo(new IdleState());

        // Level 7 — Notify observers
        Notify(new MachineEvent("ProductDispensed",
            $"{slot.Product.Name} from {slot.Code}. Change: {change:C}"));

        return VendingResult<Receipt>.Ok(receipt);
    }

    // ─── Observer management ──────────────────────────
    public void Subscribe(IMachineObserver observer)           // Level 7
        => _observers.Add(observer);

    public void Unsubscribe(IMachineObserver observer)         // Level 7
        => _observers.Remove(observer);

    private void Notify(MachineEvent evt)                      // Level 7
    {
        foreach (var obs in _observers)
            obs.OnMachineEvent(evt);
    }

    // ─── Fleet operations ─────────────────────────────
    public void SetOutOfService()                              // Level 7
        => TransitionTo(new OutOfServiceState());

    public void RestoreService()                               // Level 7
        => TransitionTo(new IdleState());
}

// ─── IChangeCalculator ────────────────────────────────
// Level 6 — Abstraction for change logic. Greedy algorithm
// in production, mock in tests.
public interface IChangeCalculator
{
    IReadOnlyList<(Denomination Coin, int Count)>? Calculate(
        decimal amount, CoinInventory inventory);
}

// ─── GreedyChangeCalculator ───────────────────────────
// Level 4 — Uses largest-first greedy approach.
public sealed class GreedyChangeCalculator : IChangeCalculator
{
    public IReadOnlyList<(Denomination Coin, int Count)>? Calculate(
        decimal amount, CoinInventory inventory)
    {
        var cents = (int)(amount * 100);
        if (cents <= 0) return [];                // Level 5 — no change needed

        var result = new List<(Denomination, int)>();
        var denoms = Enum.GetValues<Denomination>()
            .OrderByDescending(d => (int)d);

        foreach (var denom in denoms)
        {
            var coinValue = (int)denom;
            var needed = cents / coinValue;
            var available = inventory.CountOf(denom);
            var use = Math.Min(needed, available);
            if (use > 0)
            {
                result.Add((denom, use));
                cents -= use * coinValue;
            }
        }

        return cents == 0 ? result : null;         // Level 5 — null = can't make change
    }
}

// ─── IMachineObserver ─────────────────────────────────
// Level 7 — Anyone who wants to know what the machine
// is doing implements this. Dashboard, warehouse, analytics.
public interface IMachineObserver
{
    void OnMachineEvent(MachineEvent evt);
}

// ─── MachineEvent ─────────────────────────────────────
// Level 7 — Immutable event record. The machine fires
// these; observers consume them.
public sealed record MachineEvent(
    string EventType,                              // Level 7
    string Description,                            // Level 7
    DateTimeOffset Timestamp = default)            // Level 7
{
    public DateTimeOffset Timestamp { get; init; }
        = Timestamp == default ? DateTimeOffset.UtcNow : Timestamp;
}

// ─── FleetManager ─────────────────────────────────────
// Level 7 — Monitors multiple machines. In production this
// would be a dashboard service; here it logs events.
public sealed class FleetManager : IMachineObserver
{
    private readonly string _managerId;

    public FleetManager(string managerId) => _managerId = managerId;

    public void OnMachineEvent(MachineEvent evt)
    {
        Console.WriteLine(
            $"[Fleet:{_managerId}] {evt.Timestamp:HH:mm:ss} " +
            $"| {evt.EventType}: {evt.Description}");
    }
}

using Microsoft.Extensions.DependencyInjection;
using VendingMachine;
using VendingMachine.Models;
using VendingMachine.Payments;

// ─── DI Container Setup ──────────────────────────────
// Level 6 — Everything is wired through DI. No "new" calls
// scattered through business logic. This makes testing trivial:
// swap any registration with a mock.
var services = new ServiceCollection();

// Level 6 — Register change calculator as singleton
services.AddSingleton<IChangeCalculator, GreedyChangeCalculator>();

// Level 6 — Register payment gateway (could be mock in tests)
services.AddSingleton<IPaymentGateway>(new SimplePaymentGateway());

// Level 3 — Register payment strategies
services.AddTransient<CoinPayment>();
services.AddTransient<CardPayment>();
services.AddTransient<MobilePayment>();

// Level 1 — Configure product inventory
var slots = new List<Slot>
{
    new("A1", new Product("Cola", 1.25m), 10),
    new("A2", new Product("Chips", 1.50m), 8),
    new("B1", new Product("Water", 1.00m), 15),
    new("B2", new Product("Candy Bar", 0.75m), 12),
    new("C1", new Product("Energy Drink", 2.50m), 5),
};

// Level 4 + Level 6 — Build the machine with DI
services.AddSingleton(sp =>
{
    var calc = sp.GetRequiredService<IChangeCalculator>();
    return new VendingMachine.VendingMachine(slots, calc);
});

var provider = services.BuildServiceProvider();
var machine = provider.GetRequiredService<VendingMachine.VendingMachine>();

// ─── Level 7: Subscribe observers ────────────────────
var fleet = new FleetManager("HQ-01");
machine.Subscribe(fleet);

// ─── Demo Scenario ────────────────────────────────────
Console.WriteLine("=== Vending Machine Demo ===\n");

// Happy path: insert money, buy a cola
var insert1 = machine.InsertMoney(1.00m);
Console.WriteLine(insert1.Value);

var insert2 = machine.InsertMoney(0.50m);
Console.WriteLine(insert2.Value);

var purchase = machine.SelectProduct("A1");
if (purchase.Success)
{
    var r = purchase.Value!;
    Console.WriteLine($"\nReceipt:");
    Console.WriteLine($"  Product: {r.Transaction.ProductName}");
    Console.WriteLine($"  Paid:    {r.Transaction.AmountPaid:C}");
    Console.WriteLine($"  Price:   {r.Transaction.ProductPrice:C}");
    Console.WriteLine($"  Change:  {r.Transaction.ChangeGiven:C}");
    Console.WriteLine($"  Coins returned:");
    foreach (var (coin, count) in r.ChangeBreakdown)
        Console.WriteLine($"    {count}x {coin}");
}

// Edge case: try to buy without money
Console.WriteLine($"\n--- No money inserted ---");
var fail = machine.SelectProduct("A2");
Console.WriteLine(fail.Error);

// Edge case: return inserted money
machine.InsertMoney(2.00m);
var returned = machine.ReturnMoney();
Console.WriteLine($"\nReturned: {returned.Value:C}");

// ─── Simple gateway for demo ─────────────────────────
public sealed class SimplePaymentGateway : IPaymentGateway
{
    public bool Charge(decimal amount) => true;   // Always succeeds in demo
}

You've been using design patterns for the last seven levels. Some were obvious — we named them as we built them. Others are hiding in the code, doing their job quietly without anyone putting a label on them. This section is about developing pattern recognitionThe ability to look at code and see the underlying design patterns at work. Senior engineers do this unconsciously — they glance at code and immediately see "that's a Strategy" or "that's a State pattern." This skill comes from practice: once you've built patterns yourself, you spot them everywhere. — the skill of looking at code and seeing the structural bones underneath.

The Four Explicit Patterns

These are the patterns we named during the build. For each one, we'll look at where it lives in the code, what it enables, and what would happen without it.

Pattern X-Ray — See Through the Code

Here's the class diagram again, but this time with colored overlays showing which pattern each type belongs to. Blue is State, orange is Strategy, yellow is Observer, and purple marks the hidden Factory Method. Some types serve multiple patterns — that's normal and healthy.

How the Patterns Interact

Patterns don't live in isolation. Here's how they collaborateIn well-designed systems, patterns work together like gears in a machine. State delegates to Strategy (the HasMoneyState asks the payment strategy to process). Strategy produces a PaymentResult. Observer notifies on state transitions. Each pattern handles one concern and passes the result to the next. in a single purchase cycle: the State decides IF the action is allowed, Strategy handles HOW payment works, and Observer announces WHAT happened.

You've just spent seven levels building a vending machine. At Level 0 it was a single class that took money and gave items. By Level 7, it's a clean architecture with 25 types spanning state management, payment strategies, change calculation, and fleet monitoring. But it didn't happen all at once — it grew one constraint at a time. Let's zoom out and watch the whole journey unfold.

Each level below shows what was added at that stage. Glowing boxes are new arrivals; the count shows the running total. Pay attention to the growth curveThe growth curve shows how many types exist at each level. A healthy design grows gradually — 1-5 new types per level. An unhealthy design dumps 20 types in one go because someone tried to "design everything up front." Our curve is gentle because we never added more than one concept at a time. — it stays gentle because we never added more than one concept at a time.

Here's the complete picture — every entity, its type, and the level that introduced it.

You've seen the good solution — built incrementally over 7 levels. Now let's study five bad approaches that people commonly reach for. Each one is tempting for a different reason, and each one breaks in a different way. We'll show the exact code, an SVG of the problem, and the fix.

public class VendingMachineSystem
{
    private string _state = "idle";
    private decimal _balance;
    private Dictionary<string, (string Name, decimal Price, int Qty)> _slots = new();

    public string InsertMoney(decimal amount)
    {
        if (_state == "out-of-service") return "Machine broken";
        if (_state == "dispensing") return "Wait...";
        _balance += amount;
        _state = "has-money";
        Console.WriteLine($"Balance: {_balance:C}");      // display logic HERE
        return "OK";
    }

    public string BuyProduct(string code, string paymentType)
    {
        if (_state != "has-money") return "Insert money first";
        if (!_slots.ContainsKey(code)) return "Bad code";
        var (name, price, qty) = _slots[code];
        if (qty <= 0) return "Sold out";
        if (_balance < price) return "Not enough money";

        // Payment logic INLINE
        if (paymentType == "coin") { /* ... */ }
        else if (paymentType == "card") { /* ... */ }
        else if (paymentType == "mobile") { /* ... */ }

        // Change logic INLINE
        var change = _balance - price;
        // ... 40 lines of coin math ...

        // Receipt logic INLINE
        Console.WriteLine($"Receipt: {name} - {price:C}");
        Console.WriteLine($"Change: {change:C}");

        _slots[code] = (name, price, qty - 1);
        _balance = 0;
        _state = "idle";
        return "Enjoy!";
    }
    // ... 500 more lines of monitoring, restocking, diagnostics ...
}

// State: "Is this action allowed right now?"
public interface IVendingState { ... }

// Strategy: "How do we process this payment?"
public interface IPaymentStrategy { ... }

// Data: "What happened?" (immutable records)
public record Transaction(...);
public record Receipt(...);

// Observer: "Who needs to know?"
public interface IMachineObserver { ... }

// Engine: ONLY orchestration — delegates everything
public sealed class VendingMachine { ... }

// Layer 1: Abstract factories
public interface IPaymentStrategyFactory { ... }
public class PaymentStrategyFactoryProvider { ... }
public class AbstractPaymentProcessingPipeline { ... }

// Layer 2: Mediators
public interface IStateTransitionMediator { ... }
public class VendingStateMachineMediator { ... }

// Layer 3: Event bus
public interface IVendingEventBus { ... }
public class InMemoryVendingEventBus { ... }
public class CoinInsertedEventHandler { ... }
public class ProductSelectedEventHandler { ... }
public class ChangeRequestedEventHandler { ... }

// Layer 4: Specifications
public interface ISlotSpecification { ... }
public class AvailableSlotSpecification { ... }
public class PriceMatchSpecification { ... }
public class CompositeSlotSpecification { ... }

// ... and the actual VendingMachine?
// It's somewhere on line 400, buried under abstractions.

// State pattern — because we HAVE 4 modes
public interface IVendingState { ... }

// Strategy pattern — because we HAVE 3 payment methods
public interface IPaymentStrategy { ... }

// Observer — because fleet monitoring IS a real requirement
public interface IMachineObserver { ... }

// No factories, no mediators, no event buses, no specifications.
// Why? Because we don't HAVE those problems.
// Patterns solve problems. No problem → no pattern.

// Looks clean! State + Strategy, good naming.
// But watch what's MISSING:

public VendingResult<Receipt> SelectProduct(string slotCode)
{
    var slot = _slots[slotCode];  // No null check → crash on bad code
    slot.Dispense();               // No stock check → negative inventory
    var change = _balance - slot.Product.Price;
    // Returns decimal, not actual coins → can't verify physical change
    // No lock → two threads can buy the last item simultaneously
    // No timeout on dispensing → motor jam = stuck forever
}

public VendingResult<Receipt> SelectProduct(string slotCode)
{
    if (string.IsNullOrWhiteSpace(slotCode))          // L5: validate input
        return VendingResult<Receipt>.Fail("Slot code required.");

    lock (_lock)                                       // L5: atomic operation
    {
        var slot = FindSlot(slotCode);                 // L5: safe lookup
        if (slot is null) return Fail("Invalid slot.");
        if (!slot.IsAvailable) return Fail("Sold out.");
        if (_balance < slot.Product.Price) return Fail("Not enough.");

        var breakdown = _changeCalc.Calculate(         // L4: REAL coins
            _balance - slot.Product.Price, _coinInventory);
        if (breakdown is null) return Fail("Can't make change.");

        slot.Dispense();                               // Only NOW dispense
        // ... build receipt, reset state ...
    }
}

public class VendingMachine
{
    private string _state = "idle";       // Not an enum, not a class

    public string Process(string action, string slotCode, string paymentType)
    {
        if (_state == "Idle") { ... }     // Bug: capital I vs lowercase i
        // _state was set to "idle" but we check "Idle" → always false

        if (paymentType == "coin") { ... }
        else if (paymentType == "card") { ... }
        // Someone passes "Card" → falls through, no payment processed

        if (slotCode.Contains("A")) { ... } // Matches "A1" AND "BA3"
    }
}

// State: IVendingState interface → typos are impossible
private IVendingState _currentState = new IdleState();
// Misspell "IdleState"? Compiler error. Immediately. For free.

// Payment: IPaymentStrategy → no string matching
public PaymentResult Process(IPaymentStrategy strategy)
// Pass wrong type? Compiler error. Can't pass "Card" as a string.

// Slots: Dictionary lookup by exact code
var slot = _slots.GetValueOrDefault(slotCode);
// Returns null if not found — no Contains() ambiguity

public Receipt Buy(string slotCode)
{
    var slot = _slots[slotCode];
    var change = _balance - slot.Product.Price;

    // "Here's your $3.75 change!"
    // But... does the machine HAVE $3.75 in coins?
    // It doesn't know. It doesn't track individual coins.
    // It just returns a decimal and hopes for the best.

    return new Receipt(slot.Product.Name, change);
    // Customer expects 3 quarters but machine has only dimes.
    // 37.5 dimes is not a real amount of change.
}

// CoinInventory tracks REAL coins
public sealed class CoinInventory
{
    private readonly Dictionary<Denomination, int> _coins = new();
    public bool TryRemove(Denomination coin, int count) { ... }
}

// GreedyChangeCalculator checks what's physically available
public IReadOnlyList<(Denomination, int)>? Calculate(
    decimal amount, CoinInventory inventory)
{
    // Try largest coins first, fall back to smaller ones
    // If we can't make exact change → return null
    // Null means "reject the sale" — don't promise what you can't deliver
}

// In DispenseProduct:
var breakdown = _changeCalc.Calculate(change, _coinInventory);
if (breakdown is null)
    return VendingResult<Receipt>.Fail("Cannot make exact change.");

A junior developer submitted this vending machine implementation as a pull request. It compiles. It runs. It handles a basic purchase from coin insertion to item dispensing. But there are exactly 5 bugs hiding in it — issues that would cause real problems in production. Can you find them all before scrolling down?

Read the code below carefully. Try to find all 5 issues before revealing the answers.

public class VendingMachine                                        // Line 1
{
    private Dictionary<string, Slot> _slots = new();               // Line 3
    private decimal _balance;
    private string _currentState = "idle";                          // Line 5

    public string InsertMoney(decimal amount)                       // Line 7
    {
        _balance += amount;
        _currentState = "has-money";
        return $"Balance: {_balance:C}";
    }

    public string SelectProduct(string slotCode)                    // Line 13
    {
        if (_currentState != "has-money") return "Insert money first";

        var slot = _slots[slotCode];                                // Line 16
        // No null check — what if slotCode doesn't exist?

        if (_balance < slot.Product.Price)
            return "Not enough money";

        // Check stock and dispense — but NOT atomic                // Line 21
        if (slot.Quantity > 0)
        {
            slot.Quantity--;                                        // Line 23
            // Another thread could have decremented between check and here!

            var change = _balance - slot.Product.Price;
            _balance = 0;

            _currentState = "dispensing";                            // Line 28
            // What if the motor jams here?
            // _currentState stays "dispensing" FOREVER
            // No timeout, no recovery — machine is bricked

            Console.WriteLine($"Dispensing {slot.Product.Name}");
            Console.WriteLine($"Change: {change:C}");

            // _currentState should go back to "idle" but only       // Line 35
            // if dispensing SUCCEEDS — what about failures?
            _currentState = "idle";

            return "Enjoy!";
        }
        return "Sold out";
    }

    public string ProcessPayment(string paymentType, decimal amount) // Line 42
    {
        switch (paymentType)                                         // Line 44
        {
            case "coin":
                _balance += amount;
                return "Coins accepted";
            case "card":
                // Call payment API...
                return "Card charged";
            case "mobile":
                // Call mobile API...
                return "Mobile payment OK";
            default:
                return "Unknown payment type";
            // Adding cryptocurrency = modify this switch             // Line 55
        }
    }
}

Found them? Reveal one at a time:

You’ve built the entire vending machine system. Now comes the real test: can you talk through it under pressure? Below are two interview runs — the polished one and the realistic one (with stumbles, pauses, and recovery). Both get hired. The difference is how they handle the unexpected. Watch the interviewer’s inner monologue in the right column — that’s what’s actually being evaluated.

Here’s something most candidates get wrong: they treat articulation as a side-effect of knowing the design. It isn’t. Design skill and communication skill are separate muscles — you can have a brilliant vending machine design locked in your head and still tank the interview because you can’t narrate it under pressure. The 8 cards below cover the exact situations where phrasing matters most. For each one: the situation, what to say, what kills your credibility, and why the good version works.

12 questions ranked by difficulty. Each has a “Think” prompt to try first, a solid answer, and the great answer that gets “Strong Hire.” Start with the green questions to build confidence, then tackle the yellows and reds.

// Record: immutable -- name, price, code are FIXED facts
public record Product(string Name, decimal Price, string Code);

var coke = new Product("Coke", 1.50m, "A1");
// coke.Price = 2.00m;  // Compiler ERROR! Can't mutate a record.

// Class: mutable -- quantity changes every time we dispense
public class Slot
{
    public Product Product { get; }
    public int Quantity { get; private set; }

    public bool TryDispense()
    {
        if (Quantity <= 0) return false;
        Quantity--;  // This NEEDS to mutate -- that's why it's a class
        return true;
    }
}

// New file: CryptoPayment.cs -- this is ALL you write
public sealed class CryptoPayment(ICryptoWallet wallet) : IPaymentStrategy
{
    public VendingResult<PaymentReceipt> Charge(decimal amount)
    {
        var txn = wallet.SendPayment(amount);
        return txn.Confirmed
            ? VendingResult<PaymentReceipt>.Ok(new(txn.Id, amount))
            : VendingResult<PaymentReceipt>.Fail("Crypto transaction failed");
    }

    public VendingResult<decimal> Refund(decimal amount)
        => wallet.SendRefund(amount).Confirmed
            ? VendingResult<decimal>.Ok(amount)
            : VendingResult<decimal>.Fail("Crypto refund failed");
}

// DI registration -- one line in config
services.AddTransient<IPaymentStrategy, CryptoPayment>();
// VendingMachine.cs: ZERO changes. CoinPayment.cs: ZERO changes.

public sealed class ChangeCalculator
{
    // Greedy: largest denomination first, limited by physical inventory
    public VendingResult<IReadOnlyList<Coin>> MakeChange(
        decimal amount,
        Dictionary<Denomination, int> inventory)
    {
        var coins = new List<Coin>();
        var remaining = amount;

        foreach (var denom in Denomination.AllDescending()) // $1, $0.25, $0.10, $0.05
        {
            while (remaining >= denom.Value && inventory[denom] > 0)
            {
                coins.Add(new Coin(denom));
                inventory[denom]--;
                remaining -= denom.Value;
            }
        }

        return remaining == 0m
            ? VendingResult<IReadOnlyList<Coin>>.Ok(coins)
            : VendingResult<IReadOnlyList<Coin>>.Fail(
                $"Cannot make exact change. Short by {remaining:C}");
    }
}

public VendingResult<Product> Dispense(string slotCode)
{
    var slot = _machine.GetSlot(slotCode);

    // Attempt 1
    var dispensed = _dispenser.TryDispense(slotCode, timeout: TimeSpan.FromSeconds(5));
    if (!dispensed)
    {
        // Retry once -- sometimes items just need a nudge
        dispensed = _dispenser.TryDispense(slotCode, timeout: TimeSpan.FromSeconds(5));
    }

    if (!dispensed)
    {
        // Stuck item -- refund, mark slot, alert maintenance
        slot.MarkJammed();
        _machine.CurrentPayment.Refund(_machine.InsertedAmount);
        _machine.PublishEvent(MachineEvent.DispenserJam(slotCode));
        _machine.TransitionTo<IdleState>();  // other slots still work
        return VendingResult<Product>.Fail("Item stuck. Full refund issued.");
    }

    // Success path -- dispense, calculate change, transition
    slot.DecrementQuantity();
    var change = _changeCalc.MakeChange(overpayment, _machine.CoinInventory);
    _machine.TransitionTo<IdleState>();
    return VendingResult<Product>.Ok(slot.Product);
}

public interface IStatePersistence
{
    void Save(MachineSnapshot snapshot);
    MachineSnapshot? Load();
}

public record MachineSnapshot(
    string CurrentState,       // "Idle", "HasMoney", "Dispensing"
    decimal Balance,
    string? SelectedSlotCode,
    Dictionary<string, int> Inventory,
    DateTimeOffset Timestamp);

// On every state transition:
_persistence.Save(new MachineSnapshot(
    CurrentState: newState.GetType().Name,
    Balance: _balance,
    SelectedSlotCode: _selectedSlot?.Code,
    Inventory: _slots.ToDictionary(s => s.Code, s => s.Quantity),
    Timestamp: _clock.UtcNow));

// On power-up recovery:
var snapshot = _persistence.Load();
if (snapshot is not null)
{
    RestoreInventory(snapshot.Inventory);
    if (snapshot.CurrentState == "Dispensing")
    {
        // Assume dispense failed -- refund
        IssueRefund(snapshot.Balance);
        TransitionTo<IdleState>();
    }
    else if (snapshot.Balance > 0)
    {
        // Customer had money in -- restore balance
        _balance = snapshot.Balance;
        TransitionTo<HasMoneyState>();
    }
}

These aren’t hypothetical mistakes — every one of them has ended real interviews. Interviewers who’ve seen hundreds of candidates can spot them in the first five minutes. Here’s exactly what they see, and what to do instead.

● Fatal Mistakes — Interview Enders

public class VendingMachineSystem  // does EVERYTHING
{
    public void InsertMoney(decimal amount) { ... }
    public void SelectProduct(string code) { ... }
    public decimal CalculateChange(decimal paid, decimal price) { ... }  // change logic
    public bool ProcessCardPayment(string cardNumber) { ... }            // payment logic
    public void PublishEvent(string eventType) { ... }                   // event logic
    public void UpdateDisplay(string message) { ... }                    // UI logic
    // 300 more lines...
}

// BAD: switch in EVERY method, grows with every new state
public void InsertMoney(decimal amount)
{
    switch (_state)
    {
        case MachineState.Idle: _balance += amount; _state = MachineState.HasMoney; break;
        case MachineState.HasMoney: _balance += amount; break;
        case MachineState.Dispensing: throw new InvalidOperationException(); break;
        case MachineState.OutOfService: throw new InvalidOperationException(); break;
        // Add Maintenance? Touch THIS method AND SelectProduct AND Dispense AND...
    }
}

// GOOD: State pattern -- one class per mode, OCP-compliant
public sealed class IdleState : IVendingState
{
    public VendingResult InsertMoney(decimal amount, VendingMachine machine)
    {
        machine.AddToBalance(amount);
        machine.TransitionTo<HasMoneyState>();
        return VendingResult.Ok();
    }
    // Adding Maintenance = new class. THIS class: zero changes.
}

● Serious Mistakes — Significant Red Flags

● Minor Mistakes — You Lose Points, Not the Interview

Memory Palace — Walk Through a Vending Machine

Picture a real vending machine in front of you. Each physical part maps to a design step. Walk through it top to bottom, and you walk through the entire CREATES framework.

Smell → Pattern Quick Reference

5 Things to ALWAYS Mention in a Vending Machine Interview

Pattern Detection Flowchart

Flashcard Quiz — Test Your Recall

Try to answer each question before expanding. If you can nail all 5 without peeking, the vending machine is locked in your long-term memory.

You didn’t just learn a vending machine. You learned a PROCESS — a repeatable way to approach any system. The state thinking, the “what varies?” question, the physical-constraint awareness, the lock instinct, the scale bridge — none of those are vending machine tricks. They’re engineering reflexes. Below is the proof: the exact same 7 thinking tools, applied to 4 different systems. Same structure, different domain.

Six cognitive frameworks you picked up in this case study. Each one is a portable thinking tool — not a vending machine trick, but a repeatable move you can make in any LLD interview or real-world design session.

Your Toolkit Checklist

Before you leave this page, do a quick self-check. Can you explain each tool to a teammate — without looking at the page?

Three exercises that test whether you truly learned the thinking, not just memorized the code. Each one extends the vending machine with a new constraint — the kind of follow-up an interviewer might throw at you.

public interface IPromotionStrategy
{
    string Name { get; }
    decimal CalculateDiscount(IReadOnlyList<Product> items, DateTimeOffset now);
}

public sealed class BuyXGetYFree(string targetCode, int buyCount, int freeCount)
    : IPromotionStrategy
{
    public string Name => $"Buy {buyCount} {targetCode}, get {freeCount} free";

    public decimal CalculateDiscount(IReadOnlyList<Product> items, DateTimeOffset now)
    {
        var matching = items.Where(p => p.Code == targetCode).ToList();
        int sets = matching.Count / (buyCount + freeCount);
        return sets * freeCount * matching.First().Price;
    }
}

public sealed class PercentOffAfterHour(decimal percent, int afterHour)
    : IPromotionStrategy
{
    public string Name => $"{percent}% off after {afterHour}:00";

    public decimal CalculateDiscount(IReadOnlyList<Product> items, DateTimeOffset now)
    {
        if (now.Hour < afterHour) return 0m;
        return items.Sum(p => p.Price) * (percent / 100m);
    }
}

// In VendingMachine: apply best promotion
public decimal CalculateTotal(IReadOnlyList<Product> items)
{
    var subtotal = items.Sum(p => p.Price);
    var bestDiscount = _promotions
        .Select(p => p.CalculateDiscount(items, _clock.UtcNow))
        .DefaultIfEmpty(0m)
        .Max();
    return subtotal - bestDiscount;
}

// Events
public record LowStockEvent(string MachineId, string ProductCode, int RemainingQty);
public record RestockRequestEvent(string MachineId, string ProductCode, int RequestedQty);
public record ProductUnavailableEvent(string ProductCode, string Reason);

// Machine publishes when inventory drops below threshold
if (slot.Quantity <= _restockThreshold)
{
    await _eventBus.PublishAsync(new LowStockEvent(
        _machineId, slot.Product.Code, slot.Quantity));
}

// Warehouse subscribes to LowStockEvent
public class WarehouseService : IEventHandler<LowStockEvent>
{
    public async Task HandleAsync(LowStockEvent evt)
    {
        var available = _inventory.GetStock(evt.ProductCode);
        if (available > 0)
        {
            await ScheduleRestock(evt.MachineId, evt.ProductCode);
        }
        else
        {
            // Warehouse is out -- tell ALL machines
            await _eventBus.PublishAsync(new ProductUnavailableEvent(
                evt.ProductCode, "Warehouse depleted"));
        }
    }
}

// Each machine subscribes to ProductUnavailableEvent
public class MachineDisplayUpdater : IEventHandler<ProductUnavailableEvent>
{
    public Task HandleAsync(ProductUnavailableEvent evt)
    {
        _display.MarkUnavailable(evt.ProductCode);
        return Task.CompletedTask;
        // Eventually consistent -- machines update within seconds
    }
}

You’ve learned patterns, principles, and cognitive frameworks in this case study. Here’s where to go next — the pages below will deepen specific skills you’ve already started building.

Patterns Used in This Case Study

Principles Applied

Next Case Studies