Design a Vending Machine System

The ask

A buyer picks an item, pays, and the machine drops the item. The system runs many machines from one service.

Operators need stock levels for every machine. Restock visits happen before a machine runs empty.

Money must balance exactly. Every sale, refund and coin count must agree.

Most machines sit on weak links. Offline selling is a core requirement, not an extra.

Estimate the scale

The fleet holds 100,000 machines. Each machine sends a heartbeat every 60 seconds.

100,000 machines / 60 seconds = about 1,667 heartbeats per second.

Sales run at 10 per machine per day. That is a stated figure for one machine.

100,000 machines x 10 sales = 1,000,000 sales a day.

1,000,000 sales / 86,400 seconds = 12 sales per second.

The sale rate is tiny. The heartbeat rate is the steady load, and stock reports add short bursts.

API and data

The sale operation takes a machine, an item slot, a payment result and a time. It returns a sale record or a refund.

The heartbeat operation takes a machine, a time and a health summary. It returns any pending price or plan updates.

The stock operation takes a machine. It returns the count left in each slot.

A machine record holds a place, a plan of slots, a price per slot and a count per slot. The count lives on the machine and in the central service.

A sale record holds a machine, a slot, a price, a payment state and a unique sale number. The number makes a retried report safe to store twice.

High-level design

Each machine runs a local controller. The controller owns the motors, the payment reader and the local stock counts.

A fleet service receives heartbeats and sale reports. It stores the latest state for every machine.

A stock service turns sale reports into restock plans. A plan groups machines by place and by need.

A payment step runs inside the machine first. Card approval may need the network, and cash never does.

Prices and plans flow down on heartbeats. Sales and faults flow up on the same rhythm.

Deep dive: selling offline

The machine keeps the full price list and stock counts locally. A sale needs no server answer.

Each sale is written to a local log before the item drops. Power loss after payment still leaves a record.

The log carries a sale number that only grows. The central service stores each number once and ignores repeats.

Cash sales always work offline. Card sales offline carry risk, so the design caps their value and settles them later.

A machine that cannot record a sale does not sell. An unrecorded sale breaks the money balance for that machine.

Deep dive: stock truth

The machine counts a drop with a sensor in the tray. A paid sale with no drop becomes a refund and a fault.

Counts drift when items jam or fall in pairs. The sensor count corrects the slot count after each sale.

A restock worker scans the plan and the machine confirms new counts. The confirmed count replaces both copies.

Low-stock warnings fire from the central copy. A warning uses the last reported count, so a silent machine gets a visit first.

When a machine goes silent

A missing heartbeat means the link or the machine has failed. The service cannot tell which one from silence alone.

The fleet service marks the machine unknown after missed heartbeats. Its sales and stock views freeze at the last report.

A long silence raises a visit task. The task carries the last known stock, faults and cash level.

The machine keeps selling while silent. Its local log fills the gap when contact returns.

Evaluation and trade-offs

Local control keeps every machine selling through outages. The price is two copies of stock that must be reconciled.

Heartbeats give a steady, cheap health signal. A 60 second rhythm finds dead machines fast enough for a daily restock round.

Exact money records are the core promise. A vending machine system earns trust when every coin and card sale balances.

Stock views can be minutes stale. Sale records cannot be lost at all.

Scale at a glance