Amazon Locker

Package Pickup Locker System

Design a self-service parcel locker site: put each package in the smallest locker it fits, give the customer a single-use code with a deadline, handle returns, and hand overdue packages back to the courier.

Overview

A parcel locker site is a wall of compartments in three or so sizes. A courier arrives with packages, the system opens a locker that fits each one, and the customer gets a code. The customer types the code within the pickup window, the door opens, and the locker is free again. Customers can also reserve a locker to drop off a return. Packages nobody collects in time are taken back by the courier.

This is a design exercise named after a well-known product; it does not describe how Amazon builds its lockers. Interviewers like it because it mixes a fit rule (smallest locker that fits), security (codes that are hard to guess and work once), time (deadlines on every code), and a race (two couriers asking for the last small locker at the same moment).

A strong answer draws the locker states first, keeps a free list per size so allocation is O(1), generates codes with a cryptographic random source, and injects the clock so expiry can be tested exactly.

Scoping the problem

Which locker sizes exist? May a small package use a bigger locker? — Fixes the fit rule — Small, medium, large; yes, but only when no exact fit is free
How long is the pickup window? — Every code needs a deadline — A setting; the demo uses 3 days as an example, not Amazon's real window
What happens to a package after the window? — Needs an overdue state and a courier round — The code stops working; the courier takes it back
Are returns in scope? — Adds a reservation before the package exists — Yes: reserve, drop off with a code, courier collects
How are codes delivered and how long are they? — Decides how hard they are to guess — In this design: 6 digits, sent by message, single use
One site or a network? — A network needs a site chooser — One site here; nearest site with space as a follow-up
Can a door fail? — Adds a maintenance state — Follow-up

Smallest fit

Sizes are ordered, so 'fits' is a comparison: a package of size s fits any locker of size s or larger. Trying the sizes from small to large and taking the first free locker gives the smallest fit, and a free list (a deque) per size makes each take and release O(1).

PKG-1, small — S0, M0, L0 — S0 — Exact fit
PKG-2, small — M0, L0 — M0 — No small left; medium is the next size up
PKG-3, medium — L0 — L0 — Medium is taken; large still fits
PKG-4, small — none — refused — NoLockerAvailable

The cost of this rule is that a small parcel can use up the last medium locker. If that hurts, keep a reserve: let a small parcel move up only while more than N lockers of the bigger size are free. It is a one-line change in _take.

Codes and deadlines

A code is six digits drawn from Python's secrets module, which the Python documentation says to use for security tokens instead of random, whose generator is meant for simulation. A new code is redrawn if it clashes with a live code at the same site. It is deleted when used, so it works once, and it stops working at its deadline, which is set from an injected now.

The code exists — A typo or a guess
The code is of the right kind — A return code opening a delivery locker
now is before expires_at — A late customer opening a locker the courier is about to empty
Delete on success — Opening the same door twice

expire(now) is what a scheduled job calls. It removes every late code; a late pickup code turns its locker Overdue and flags it for the courier, while a late return reservation just frees its locker, since nothing was put in.

Thread safety

Two couriers can ask for the last small locker in the same instant. Without a lock both could see it in the free list and both could be told to use it. Every public method of LockerSite runs under the site's single lock, so taking a locker, marking it and creating its code is one atomic step, and so is checking and deleting a code. One lock per site is enough: in this design a site is small (tens of lockers), each operation holds the lock for microseconds, and different sites never share state. The demo sends 10 couriers with small parcels at a site with 3 small and 2 medium lockers and asserts that exactly 5 succeed, into 5 different lockers, with 5 different codes.

What you will be able to do

State the fit rule as an ordering of sizes and implement smallest fit with a free list per size.
Draw the locker states, including returns and overdue packages, and name what moves each arrow.
Generate single-use, expiring codes with a secure random source, and list the checks a pickup must pass.
Explain the race between couriers and where the lock goes.

Functional requirements

A site has lockers of three sizes; a package goes into the smallest free locker it fits
deliver(package, size, now) assigns a locker and returns a 6-digit pickup code with a deadline, or refuses when nothing fits
pickup(code, now) opens the locker once for a valid, unexpired pickup code and frees it
request_return(package, size, now) reserves a locker and returns a drop-off code; drop_off(code, now) records the package
expire(now) voids late codes: overdue deliveries and dropped-off returns are listed for the courier, unused reservations are freed
collect(locker_id) lets the courier empty only lockers flagged for collection

Non-functional requirements

No locker is given to two packages: every operation runs under the site lock
Taking and releasing a locker is O(1): a free list per size
Codes come from a cryptographic random source, are unique among live codes, single use and time limited
Time is injected, so expiry is exact in tests
The pickup and return windows are settings, not constants in the logic

Interview questions

Six digits is only a million codes. Can someone guess one?
The customer chose a site that is full. What then?
A locker door jams. How does the design cope?
Thousands of sites report to one backend. Where does the lock go then?
How is the customer told the code, and reminded before the deadline?