Notes
Requirements
Fix the scope. Lockers sit in many locations, each with small, medium and large slots. A courier drops a parcel into the smallest free slot that fits in the customer's area. The customer gets a six digit code that opens that slot exactly once. If they do not collect it within three days, the parcel goes back to the sender. Many couriers work at once. Payment and the door hardware are out of scope.
- lockers in many locations
- slots: small, medium, large
- courier drops a parcel in the
- smallest slot that fits
- customer gets a 6-digit code
- code opens the slot once
- collect within 3 days, else the
- parcel goes back to the sender
- many couriers at once
- out of scope: payments, hardware
Entities
Underline the nouns: locker, slot, parcel, code. A locker has an id, a pincode and a list of slots. A slot has a size and holds at most one deposit. The deposit is the key idea: a small immutable record bundling the parcel, its pickup code and its expiry time. Because the three always change together, keeping them in one record means a slot is either fully empty or fully filled, never half.
enum Size { SMALL, MEDIUM, LARGE }
record Parcel(String id,
String customer, Size s)
record Deposit(Parcel parcel,
String code, Instant exp)
class Slot: id, size,
AtomicReference<Deposit> held
record Locker(String id,
String pincode, List<Slot>) Class diagram
Where does the rule live that a large box cannot go in a small slot? On the slot, because the slot owns its size. Declare the sizes in order from small to large and the rule becomes one comparison: a slot fits a parcel if its size is at least the parcel's size. Adding an extra large size later is one new enum value, and the rule still works.
boolean fits(Parcel p) {
return size.compareTo(p.size()) >= 0;
}
enum order is SMALL < MEDIUM < LARGE
small parcel: any slot
medium parcel: medium or large
large parcel: large only Strategy: slot choice
Which slot to use is a policy, so it sits behind a strategy. Our default is best fit: look at lockers in the customer's pincode, keep free slots that fit, and sort smallest first. A small parcel takes a small slot if one is free, and only spills into a medium one when all small slots are full, so large slots stay free for large parcels. A nearest-to-home or wear-levelling policy would be a new class.
interface SlotStrategy {
List<Slot> candidates(List<Locker> l,
Parcel p, String pin);
}
BestFit: lockers in the pincode,
free slots that fit,
smallest size first
later: nearest to the customer,
spread wear across lockers Flow: deposit
The deposit flow. Ask the strategy for candidate slots in order. For each one, reserve a fresh pickup code, build the deposit with an expiry three days out, and try to fill the slot. If another courier filled it a moment earlier, release the code and try the next slot. On success, text the customer their code and tell the courier which door to open. If nothing fits, return empty so the courier takes the parcel to a depot.
for (Slot s : strategy.candidates(..)) {
String code = reserveCode(s);
Deposit d = new Deposit(p, code,
now + 3 days);
if (!s.tryFill(d)) {
codes.remove(code, s); continue;
}
notifier.send(customer, code);
return Optional.of(s.id);
}
return Optional.empty(); // depot Concurrency
Two couriers at the same locker both see slot M1 free. If filling were check then set, both would put a parcel in one slot. Instead the slot holds an atomic reference and filling is compare-and-set from empty to this deposit. Exactly one wins and the other moves on. Emptying is compare-and-set from this exact deposit to empty, so a slow pickup can never clear a newer parcel that has since been put in the same slot.
AtomicReference<Deposit> held
boolean tryFill(Deposit d) {
return held.compareAndSet(null, d);
}
boolean tryEmpty(Deposit d) {
return held.compareAndSet(d, null);
}
tryEmpty only clears THIS deposit Flow: pickup
The pickup flow. The first step is to remove the code from the code index. Removal is atomic, so if someone types the same code twice, or two people race with it, only one removal finds the slot and the other gets wrong or used code. Then check the expiry, empty the slot with compare-and-set and open the door. One atomic remove is what makes the code one-time.
Slot s = codes.remove(code);
if (s == null) throw: wrong or used
Deposit d = s.deposit();
if (now > d.expires()) {
codes.put(code, s); // for sweep
throw: expired, being returned
}
s.tryEmpty(d);
return d.parcel(); // open the door Security
The pickup code is a secret, so treat it like a password. Generate it with a secure random source, not the ordinary random class. Reserve it with put-if-absent so no two live parcels share a code. It works once and dies with the deposit. A keypad should lock after a few wrong tries in a row, since six digits is only a million guesses, and a real system stores a hash of the code rather than the code itself.
- SecureRandom, not Random
- unique among live codes:
- reserve with putIfAbsent
- one use, then gone
- expires with the deposit
- lock the keypad after 5 wrong
- tries in a row
- never log the code
- real system: store a hash
Expiry
Uncollected parcels need to go back. A sweep runs once a day, finds deposits past their expiry, empties those slots with the same compare-and-set, removes their codes and produces the list of parcels the courier should collect. The customer is told their parcel is being returned. The pickup flow also refuses expired codes, so a customer cannot open a slot the courier is about to empty.
for each slot with a deposit:
if (now <= d.expires()) continue;
if (s.tryEmpty(d)) {
codes.remove(d.code());
back.add(d.parcel());
notify: returned to sender
}
return back; // the courier's list Notifications
Notifications sit behind a tiny interface. The locker system decides what to say: your parcel is in slot M1 with this code, a reminder on day two, your parcel has been returned. The notifier decides how: SMS, an app push, or email. Each channel is an implementation, so adding WhatsApp never touches the locker logic, and tests just record the messages.
interface Notifier {
void send(String customer,
String message);
}
events: deposited (with code),
reminder on day 2, returned
SMS, app push and email are
just implementations Concurrency
Check every shared field. Slot contents are an atomic reference, filled and emptied only with compare-and-set. The code index is a concurrent hash map: put-if-absent to reserve a code and remove to use it. Deposits and parcels are immutable records. The list of lockers is built at start-up and only read afterwards, and notifications are sent without holding anything.
- slot contents: AtomicReference
- fill and empty with CAS
- codes: ConcurrentHashMap
- reserve: putIfAbsent
- use: remove (one-time)
- deposit, parcel: immutable
- locker list: built at start
- notifications: outside any lock
Extensibility
Now the follow-ups. Let the customer choose a locker at checkout? Reserve a slot ahead with an expiry, like a booking hold. Customer returns? A deposit whose code is sent to the courier instead. A broken door? An out-of-order flag the strategy skips. Chilled slots for groceries? A new slot feature and a strategy rule. With thousands of lockers, keep a free-slot index per locker and size instead of scanning.
- customer picks the locker:
- reserve a slot at checkout
- returns by customers: a deposit
- with a courier pickup code
- slot out of order: a flag the
- strategy skips
- temperature slots: a new
- feature + strategy rule
- many lockers: index free slots
- per locker and size
Testing
The full code is below the player. The demo fills a small slot, spills the next small parcel into a medium slot, sends a large parcel to the depot when no large slot is left, uses a code once and rejects it the second time, moves a fake clock four days forward to expire a parcel, runs the return sweep, and lets ten couriers race for four fitting slots. Exactly four parcels are placed, in four different slots.
P1 (small) -> BLR1-S1 P2 (small) -> BLR1-M1 (size up) P3 (large) -> BLR1-L1 P4 (large) -> no slot, depot asha picks up: P1 same code again: wrong or used ravi after 4 days: expired sweep returned: [P2, P3] Race: 10 parcels, 4 slots, placed 4
Say it like this
Here is the short version to say out loud. Lockers have slots, and a slot holds one immutable deposit: the parcel, its code and its expiry. Best fit is a strategy. Slots fill and empty with compare-and-set, so couriers never collide. Codes are secure random, unique among live parcels, and removed on use, so each works once. A daily sweep sends expired parcels back.
- "Lockers have slots; a slot
- holds one immutable Deposit:
- parcel, code, expiry. Best fit
- is a strategy. Slots fill and
- empty with compare-and-set.
- Codes are secure random,
- unique, and removed on use, so
- they work once. A daily sweep
- returns expired parcels."