## 1. 📦 What is Amazon Locker? Amazon Locker is a self-service pickup system: instead of leaving a package at your door, a courier drops it into a secure locker compartment at a nearby pickup location, and you collect it yourself with a one-time code. When the courier deposits a package, the system picks a free compartment that fits the package size and issues a pickup code that is valid for a few days. You go to the locker, enter the code, the right compartment pops open, and you take your package. The code stops working after that, the compartment is free for the next package, and anything you never pick up eventually goes back to the courier. The software model does not need to represent door latches, barcode scanners, *SMS (Short Message Service)* gateways, or payments. It needs to assign compartments, track occupancy, issue and redeem one-time codes exactly once, and avoid check-then-act bugs when a compartment is assigned or freed. ## 2. Requirements The interesting part of Amazon Locker is not the hardware, it is the small set of lifecycle and one-time-code rules the software must never break, plus a few clarifying questions about how much overlap or concurrency is in scope. ### Clarifying Questions ::::qa-item :::you[You] "Are we modeling the physical hardware here, the door latches, the scanners, the screen, or just the software object model that decides which compartment opens?" ::: :::interviewer[Interviewer] "Just the object model. Assume the hardware exposes a simple open-compartment call. Focus on responsibilities, lifecycle, and correctness." ::: :::takeaway[Takeaway] This rules out door, scanner, and screen classes. The system is an in-memory object graph, so opening a compartment is one method call. ::: :::: ::::qa-item :::you[You] "When a courier drops off a package, does the system pick the compartment, or does the courier choose one? Does the package itself carry anything richer than a size?" ::: :::interviewer[Interviewer] "The system picks. It allocates the smallest free compartment that fits the package's size class. At baseline the package is just a size and a lifecycle state." ::: :::takeaway[Takeaway] Allocation is an orchestrator responsibility, not the courier's. Package size is a closed enum, so there is no rich `Package` subtype hierarchy. ::: :::: ::::qa-item :::you[You] "What is the rule for a pickup code? One active code per package, and what happens to it after a successful pickup or after it expires?" ::: :::interviewer[Interviewer] "Exactly one active code per package. After a successful pickup the code is dead, and an expired code is dead too. Both are terminal, and replaying a code that already worked must not re-open anything." ::: :::takeaway[Takeaway] The code has a small lifecycle, not just a boolean. Some object must own redeemed-at-most-once and expiry, which points at a dedicated reservation record rather than a flag on the package. ::: :::: ::::qa-item :::you[You] "When a code is rejected, does the caller need to know why it failed, or is a single yes/no enough?" ::: :::interviewer[Interviewer] "The caller needs the specific reason. Invalid, expired, already redeemed, and wrong location are all distinct outcomes the front end will message differently." ::: :::takeaway[Takeaway] Pickup returns a typed result enum, not a boolean, and every guard runs before any compartment opens. ::: :::: ::::qa-item :::you[You] "Two couriers could hit the same location at the same moment, and a customer could redeem a code right as an expiry sweep runs. Do we need to be correct under that concurrency?" ::: :::interviewer[Interviewer] "Yes. Concurrent drop-offs must never hand the same compartment to two packages, and a redeem racing the expiry sweep must resolve to exactly one outcome. That correctness is the bar." ::: :::takeaway[Takeaway] The ownership of compartment assignment and code redemption has to be clear, with guards on the owning objects rather than flags a caller reads then sets. That gives the baseline design one place to enforce each transition and a clean place to add synchronization if concurrency matters. ::: :::: ### Functional requirements - The system models a pickup location holding compartments in four fixed size classes: `SMALL`, `MEDIUM`, `LARGE`, and `XL`. - A courier deposits a package, and the system allocates the smallest free compartment whose size class fits, using a best-fit rule. - On allocation, the system issues a one-time pickup code with an expiry window, bound to the package and compartment. - A customer redeems the code, and on a valid, unexpired, unredeemed code the right compartment opens, the package is released, the code is invalidated, and the compartment is freed. Redemption is idempotent, and it returns a typed outcome for each failure: invalid code, expired code, already-redeemed code, and wrong-location attempt. - Unclaimed packages expire after a retention window and are reclaimed, freeing the compartment and marking the package for courier return. - The system enforces legal lifecycle transitions for both the package and the compartment, and drop-off returns a typed no-capacity outcome when no fitting compartment is free. ::::collapse[Out of scope]{variant="warning"} - Physical hardware: door latches, barcode scanners, the locker screen, and the device network. - Notification delivery: real SMS or email gateways. The notification channel is named only as a future seam. - Payments, billing, and any checkout flow. - Persistence, databases, and distributed coordination. This is a single-process, in-memory model. - Multi-location availability queries and routing across pickup locations. - Full 3D bin-packing or continuous-dimension fit. :::: ## 3. Choosing the Core Objects With scope settled, the first design move is to turn the prompt's nouns into the few objects that actually carry state and behavior. The requirements name a lot of things, but most of them are not classes. A few nouns jump out: location, compartment, package, pickup code, courier, customer, size class, and status. Some are real entities, while others only look like entities on first read. A noun needs a class only when it owns state or behavior the system must manage. - `LockerLocation` is the obvious coordinator. Something has to hold the compartment inventory, run drop-off and pickup, keep a fast lookup from a live code to its reservation, and run the expiry sweep. No single compartment or package can do that, which makes it the orchestrator. - `Compartment` is real because it owns state that exists in the physical world regardless of any software: it is free, reserved, or occupied, and at most one package can be inside it. That intrinsic occupancy is the kind of state an entity should own. - `Package` is worth a second look. It is tempting to skip it, since at deposit time all the system needs is a size. But the package also moves through its own lifecycle, from awaiting pickup to picked up, expired, or returned, and that status has to live somewhere. So `Package` stays as a small entity, not a class with a subtype per size. - `Assignment` is the one entity that is not a literal noun in the prompt. When a package is dropped off, a single reservation binds the package, the compartment, the code, the entry time, and the expiry deadline together. That reservation needs its own identity and lifecycle. That leaves the obvious rejections. `SizeClass` and the lifecycle statuses are closed sets with no behavior, so they are enums. `Courier` and `Customer` are actors who call methods, not classes, holding no account or history the system has to remember. An admin appears only to drive a compartment to `OUT_OF_SERVICE`, one method call. ### Why not model the pickup code as its own entity? The pickup code is worth a closer look because it is central enough that a separate `AccessCode` class initially seems reasonable. ::::collapse[Bad Solution: A standalone AccessCode entity]{variant="bad"} Make the code its own class that owns its value, its expiry deadline, and a redeemed flag, and let pickup read and update that object directly. Every one of those fields is reservation state. One active code per package, its expiry, and redeemed-at-most-once all describe a single reservation, so an `AccessCode` duplicates what the `Assignment` already holds and splits the at-most-once invariant across two objects. That split makes concurrent redemption harder to enforce in one place. :::: ::::collapse[Good Solution: Code state on Assignment, generation behind a seam]{variant="good" open} Keep the entry time, expiry, and redeemed flag on the `Assignment`, the object that already owns the reservation, so the at-most-once guard lives in one place. What genuinely varies is how a code is generated and verified, a *one-time password (OTP)* today, maybe a barcode or app token later. That belongs behind a thin `PickupCredential` seam, a swappable code-scheme object rather than a new entity. The code does not need its own entity because its lifecycle state already belongs to the reservation. :::: ### Entity role summary | Entity | Role | |--------|------| | `LockerLocation` | Orchestrator: owns the compartment inventory, the free-compartment index, drop-off and pickup entry points, and the expiry sweep | | `Compartment` | Owns intrinsic occupancy and lifecycle state and knows its size class, the physical resource that gets allocated | | `Package` | Data holder with a small lifecycle, carrying its required size class and its status | | `Assignment` | Reservation record binding package, compartment, and credential, and the home of entry time, expiry deadline, and the redeemed flag | | `PickupCredential` | Behavior seam for issuing and verifying a one-time code, with OTP as the default implementation | ::img[Entity relationship map]{src="https://assets.hack2hire.com/post/6a20b0958b879849ebc119f7/b7e798ad-6dd5-465d-ab25-937adfb0307e_20260603.svg"} ## 4. Shaping the Class Design With the four core objects settled, the next step is deciding what state each one owns and what methods it exposes. The key questions are who knows whether a compartment is taken and where the one-time-code rules live. Those ownership decisions determine how deposit, pickup, and expiry can be guarded consistently. ### The orchestrator that coordinates deposit and pickup `LockerLocation` coordinates everything but should not try to be everything: its job is to manage compartments and reservations, not to be one. From the requirements it does four things: find a fitting free compartment fast, look up a reservation from a presented code, answer how many compartments of a size are free, and sweep expired reservations. That gives it the compartments it composes, plus two indexes: a free-compartment index per size class so allocation and availability are *O(1)* instead of a linear scan, and a map from active code to `Assignment` so pickup is *O(1)* instead of scanning every reservation. Both are caches maintained by the location. The location does not compute time or generate codes itself. An injected clock makes expiry testable, while an injected credential scheme keeps code generation and verification replaceable. ```js class LockerLocation: - locationId: String - compartments: List - freeCompartmentsBySize: Map> - activeAssignmentsByCode: Map - credentialScheme: PickupCredential - clock: Clock - retentionWindow: Duration + depositPackage(pkg: Package) -> DropOffResult + pickup(code: String) -> PickupResult + reclaimExpired() -> List + availability(size: SizeClass) -> int ``` The index and the code map live here because they are relationships the system manages, not facts about any one compartment. A compartment does not know how many of its siblings are free, and a code means nothing to the compartment that will eventually open. ### The compartment: where occupancy lives Now the first real fork. A tempting first move is to track occupancy on the location, as a single free count per size. That works for a single deposit, but it breaks the moment two couriers both read "one free" and both decrement: they can hand the same compartment to two packages. The physical compartment is the thing that is occupied, so its status is authoritative and belongs on it. That is intrinsic state, data that belongs to the thing itself. The compartment owns its `CompartmentStatus` and a reference to the assignment currently holding it, and it exposes guarded transitions, methods that refuse an illegal state change before acting. ```js class Compartment: - compartmentId: String - locationId: String - size: SizeClass - status: CompartmentStatus - heldBy: Assignment + fits(pkg: Package) -> boolean + reserve(assignment: Assignment) -> void + occupy() -> void + release() -> void + markOutOfService() -> void ``` The reason `reserve` and `release` live here, rather than as flag-flips on the location, is that they are the compartment's own legal transitions. `reserve` only succeeds from `AVAILABLE`, `release` only from `RESERVED` or `OCCUPIED`. Putting the guard on the owning object gives the design one authoritative place to reject an illegal second assignment once the caller has entered the guarded flow. The free-compartment index on the location is the relational counterpart to this intrinsic state, a cache derived from compartment status, never a second source of truth. > [!TIP] > In the interview I'd say: "Physical occupancy is intrinsic to the compartment. It is true regardless of any software. The location's free-compartment count is relational. It is just an index the system keeps. I model them separately so the compartment owns its own truth and the index is only ever a cache over it." ### The reservation record: Assignment We have a compartment that owns occupancy and a location that indexes it. The missing piece is the one-time-code rules. A natural instinct is to stash the code, the expiry, and a redeemed flag on the `Package`. That works until you trace a redemption: if the redeemed flag is a value a caller reads then sets, two redemptions can both read "not redeemed" before either writes. The invariant is enforced by callers, which is to say it is not really enforced. That gap is what `Assignment` fills. It is the record of this one reservation, the single object that binds the package, the compartment, and the credential, and owns the entry time, the expiry deadline, and the redeemed flag. Because all of that lives on one object, `redeem` is the single place that checks not-already-redeemed and not-expired before advancing the package to `PICKED_UP`. ```js class Assignment: - assignmentId: String - pkg: Package - compartment: Compartment - code: String - entryTime: Instant - expiresAt: Instant - redeemed: boolean + isExpired(now: Instant) -> boolean + redeem(now: Instant) -> boolean + expire(now: Instant) -> boolean ``` The expiry and redeemed state live here, not on the compartment, because they are intrinsic to the single reservation the `Assignment` represents, not to the physical resource. Put them on the compartment and they leak reservation concerns into a resource that gets reused: the next package in the same compartment would inherit a stale redeemed flag. Keeping them on the `Assignment` means each reservation carries its own clean lifecycle. > [!NOTE] > `Assignment` keeps the one-time-code lifecycle separate from physical occupancy. The compartment guards whether it can hold a package, while the assignment guards whether that reservation can be redeemed or expired. This state-ownership split gives each at-most-once guarantee one object that can enforce it. ::::collapse[Bad Solution: A redeemed flag the caller checks then sets]{variant="bad"} The simplest model puts a `redeemed` boolean and an expiry timestamp loosely on the package, and lets the location keep occupancy as flags it flips. Pickup reads `redeemed`, does the work, then sets it true. Deposit reads the free count, picks a compartment, then marks it taken. This collapses under exactly the concurrency the requirements demand. Two redemptions arriving together both read `redeemed` as false before either writes it, so both open the compartment. Two deposits both see the last compartment as free and both claim it. The invariant lives in the gap between a caller's check and its act, the classic check-then-act race. It looks correct in a single-threaded trace and fails the moment two actors overlap. :::: ::::collapse[Good Solution: Owned state guarded by one coarse location lock]{variant="warning"} A real improvement is to move occupancy onto the compartment and the redeemed flag onto the `Assignment`, then wrap every deposit and pickup in a single per-location lock. Now there is one clear home for each piece of state, and the lock serializes the check-then-act sequences so no two callers interleave inside them. This is the baseline guarantee the reference implementation actually provides, and for many interviews it is a fine place to land. The cost is that the lock is coarse: every operation at the location blocks every other, even when a deposit into a small compartment has nothing to do with a pickup from a large one. Under load the whole location becomes a single lane. It protects the invariant by serializing everything, which works but does not try to exploit finer-grained independence. :::: ::::collapse[Great Solution: Small guarded transitions on the owning objects]{variant="good" open} A further refinement would keep occupancy intrinsic to `Compartment` and the one-time-code state on `Assignment`, and then add narrower synchronization around the owned transitions. Reserve-plus-issue would still be centered on the compartment guard, and verify-plus-redeem on the `Assignment` guard. That is a reasonable next step to discuss in an interview, but it is beyond the baseline code shown here. The important baseline story is still the ownership split: the compartment owns occupancy, the assignment owns redemption and expiry, and the public operations can be serialized cleanly around those owned transitions. :::: ### The data holders and the seams With occupancy and the reservation record settled, the remaining pieces are quick: `Package` is a small entity and the enums are closed sets. ```js class Package: - packageId: String - requiredSize: SizeClass - status: PackageStatus enum SizeClass: SMALL MEDIUM LARGE XL enum PackageStatus: AWAITING_PICKUP PICKED_UP EXPIRED RETURNED enum CompartmentStatus: AVAILABLE RESERVED OCCUPIED OUT_OF_SERVICE ``` The lifecycle diagrams show which package and compartment transitions the guarded methods allow and reject. ::img[Package lifecycle]{src="https://assets.hack2hire.com/post/6a20b0958b879849ebc119f7/188c984e-ab57-4744-8dd5-925bb99cbb53_20260603.svg"} ::img[Compartment lifecycle]{src="https://assets.hack2hire.com/post/6a20b0958b879849ebc119f7/f46a5ce5-f74b-4928-bdb4-60b41b88a2f1_20260603.svg"} The requirements anticipate alternate credential schemes, so generation and verification sit behind `PickupCredential`, with a one-time OTP as the default. Expiry depends on an injected `Clock`, a time source tests can control, and an injected `CodeGenerator` makes issued codes deterministic. Allocation remains a concrete best-fit rule because no alternate policy is required at baseline. ```js class PickupCredential: + issue(assignment: Assignment) -> String + verify(presentedCode: String, assignment: Assignment) -> boolean class Clock: + now() -> Instant class CodeGenerator: + generate() -> String ``` ### Final class design Putting it together, here is the full design in one place, shown below as a *Unified Modeling Language (UML)* class diagram. ```js class LockerLocation: - locationId: String - compartments: List - freeCompartmentsBySize: Map> - activeAssignmentsByCode: Map - credentialScheme: PickupCredential - clock: Clock - retentionWindow: Duration + depositPackage(pkg: Package) -> DropOffResult + pickup(code: String) -> PickupResult + reclaimExpired() -> List + availability(size: SizeClass) -> int class Compartment: - compartmentId: String - locationId: String - size: SizeClass - status: CompartmentStatus - heldBy: Assignment + fits(pkg: Package) -> boolean + reserve(assignment: Assignment) -> void + occupy() -> void + release() -> void + markOutOfService() -> void class Assignment: - assignmentId: String - pkg: Package - compartment: Compartment - code: String - entryTime: Instant - expiresAt: Instant - redeemed: boolean + isExpired(now: Instant) -> boolean + redeem(now: Instant) -> boolean + expire(now: Instant) -> boolean class Package: - packageId: String - requiredSize: SizeClass - status: PackageStatus class PickupCredential: + issue(assignment: Assignment) -> String + verify(presentedCode: String, assignment: Assignment) -> boolean class Clock: + now() -> Instant class CodeGenerator: + generate() -> String enum SizeClass: SMALL MEDIUM LARGE XL enum PackageStatus: AWAITING_PICKUP PICKED_UP EXPIRED RETURNED enum CompartmentStatus: AVAILABLE RESERVED OCCUPIED OUT_OF_SERVICE ``` ::img[Full UML class diagram]{src="https://assets.hack2hire.com/post/6a20b0958b879849ebc119f7/4d934c2e-0fa7-4c93-9263-53fdb9b405bd_20260603.svg"} ## 5. Key Flow Walkthroughs With the class boundaries settled, the next question is what the key methods actually do. Three methods carry the system, plus one small helper: depositing a package, picking one up, reclaiming the ones nobody collected, and the size-fit check that drives allocation. Each follows the same discipline, run every check that could fail before touching any state. > [!TIP] > Before diving in, check with your interviewer. Some want working code, others prefer pseudocode, and some just want you to talk through the logic. We'll use reader-friendly structural pseudocode here, then point to a complete compilable reference implementation at the end. ### Deposit a package The happy path is not the interesting part of deposit. The interesting part is making the reserve step the state transition that decides whether the drop-off can proceed, rather than letting callers reason from a stale free-count check. We pull a best-fit free compartment from the index, returning a typed no-capacity result before anything mutates if none exists. If one exists, the reserve transition itself is the guard inside the baseline flow: it succeeds only if the compartment is still `AVAILABLE`. ```js depositPackage(pkg) compartment = findBestFitFreeCompartment(pkg.requiredSize) if compartment == null return DropOffResult.noCapacity() // reserve succeeds only if still AVAILABLE compartment.reserve(newAssignment) freeCompartmentsBySize.get(compartment.size).remove(compartment) assignment = Assignment(pkg, compartment, clock.now(), retentionWindow) code = credentialScheme.issue(assignment) assignment.code = code compartment.occupy() activeAssignmentsByCode.put(code, assignment) pkg.status = AWAITING_PICKUP return DropOffResult.success(code) ``` The choice that matters is the ordering. We do not issue a code before the `reserve` succeeds, because reserving is the step that can fail and should happen before the rest of the bookkeeping. ::img[Responsibility flow: depositPackage]{src="https://assets.hack2hire.com/post/6a20b0958b879849ebc119f7/f655789b-ed4a-4fec-b8a3-419b1db1e9e9_20260603.svg"} ### Pick up a package Pickup must enforce redeem-at-most-once. Every failure reason is checked before any compartment opens: resolve the reservation from the code, run the guards, then perform the state changes. The failure cases map directly to the typed result the requirements asked for: - no reservation for this code at all returns `INVALID` - a reservation that belongs to a different location returns `WRONG_LOCATION` - a reservation already past its deadline returns `EXPIRED` - a reservation already redeemed returns `ALREADY_REDEEMED` ```js pickup(code) assignment = activeAssignmentsByCode.get(code) if assignment == null return PickupResult.invalid() if assignment.compartment.locationId != locationId return PickupResult.wrongLocation() if assignment.isExpired(clock.now()) return PickupResult.expired() // The at-most-once guard returns false if already redeemed if not assignment.redeem(clock.now()) // Marks redeemed, sets package PICKED_UP return PickupResult.alreadyRedeemed() assignment.compartment.release() freeCompartmentsBySize.get(assignment.compartment.size).add(assignment.compartment) activeAssignmentsByCode.remove(code) return PickupResult.success(assignment.compartment) ``` The non-obvious choice is that the real at-most-once check lives in `redeem`, not in a separate boolean the caller reads first. A naive version would read `assignment.redeemed`, decide it is false, then do the work, which is exactly the check-then-act shape you want to avoid. Instead, `redeem` owns the check and the state flip, and callers branch on its return value. Idempotency falls out cleanly: a replay of a completed code either misses the active map and returns `INVALID`, or reaches a reservation whose owned guard no longer allows redemption. ::img[Responsibility flow: pickup]{src="https://assets.hack2hire.com/post/6a20b0958b879849ebc119f7/1c63fd48-f62f-49a6-aee9-4c9732c8c456_20260603.svg"} ### Reclaim expired reservations The sweep walks active assignments past their deadline and frees each one through the same legal transition a normal pickup uses. Lazy-on-access expiry and the sweeper must funnel through one transition rather than maintain two code paths that can diverge. ```js reclaimExpired() reclaimed = [] for assignment in activeAssignmentsByCode.values() if not assignment.isExpired(clock.now()) continue // Same guarded redeem-or-expire transition the pickup path respects if assignment.expire(clock.now()) // Succeeds only if not already redeemed assignment.pkg.status = EXPIRED assignment.compartment.release() freeCompartmentsBySize.get(assignment.compartment.size).add(assignment.compartment) activeAssignmentsByCode.remove(assignment.code) reclaimed.add(assignment) return reclaimed ``` A customer's redeem can arrive at the same instant the sweep decides the assignment is expired. The baseline design keeps both outcomes centered on the same `Assignment` state, so redeem and expire do not update separate pieces of truth. In the Java reference, location-level synchronization serializes those paths; the Python reference models the same ownership split without explicit threading primitives. ### Check whether a compartment fits `fits` is small but precise, because it encodes the best-fit rule the allocator depends on. A compartment fits a package when its size class is at least the package's required size, under the ordering `SMALL` < `MEDIUM` < `LARGE` < `XL`. The allocator then picks the smallest fitting size that has a free compartment. ```js fits(pkg) return size.ordinal >= pkg.requiredSize.ordinal ``` Keeping `fits` on the compartment, rather than as a free-floating rule in the location, gives the size-comparison logic one home. ### A concrete example It is worth running one session end to end, because this is where the ownership split stops being theoretical. Watch the compartment's status and the location's free-compartment index stay aligned, and the reservation move through one terminal path. - A courier deposits a medium package. `findBestFitFreeCompartment(MEDIUM)` returns compartment "M3", currently `AVAILABLE`. - `M3.reserve(...)` flips it to `RESERVED` first, then the location removes "M3" from `freeCompartmentsBySize`. The status changes before the index, because the status is the source of truth and the index only follows it. - An `Assignment` is created, the credential scheme issues code "4821" with a 3-day expiry, "M3" goes `OCCUPIED`, and `activeAssignmentsByCode` gains "4821". - Two days later the customer calls `pickup("4821")`. The guards pass, `redeem` marks the assignment redeemed and the package `PICKED_UP`, `M3.release()` returns it to `AVAILABLE`, and the location adds "M3" back to the free index and drops "4821" from the active map. - A second attempt with "4821" now misses the active map and returns `INVALID`. The compartment is not touched. That trace is the consistency story: because the compartment status flips first and the index only follows, the baseline flow keeps one source of truth for whether "M3" is actually available. ### Complete code implementation The walkthroughs above use pseudocode to keep the flow readable. A full, compilable reference implementation in both Java and Python follows, with the complete class definitions, the guarded transitions, the typed result objects, and the injected clock and credential seams wired together. The baseline references focus on state ownership and legal transitions; the Java version serializes public operations at the location level, while the Python version mirrors the same model without adding explicit locking primitives. ::::code :::java import java.time.*; import java.util.*; class AmazonLocker { public enum SizeClass { SMALL, MEDIUM, LARGE, XL } public enum PackageStatus { AWAITING_PICKUP, PICKED_UP, EXPIRED, RETURNED } public enum CompartmentStatus { AVAILABLE, RESERVED, OCCUPIED, OUT_OF_SERVICE } public enum PickupOutcome { SUCCESS, INVALID, EXPIRED, ALREADY_REDEEMED, WRONG_LOCATION } public enum DropOffOutcome { SUCCESS, NO_CAPACITY } public interface Clock { Instant now(); } public static final class SystemClock implements Clock { @Override public Instant now() { return Instant.now(); } } public interface CodeGenerator { String generate(); } public static final class NumericCodeGenerator implements CodeGenerator { private long counter = 0; @Override public String generate() { counter += 1; long value = (counter * 7919L) % 1_000_000L; return String.format("%06d", value); } } public interface PickupCredential { String issue(Assignment assignment); boolean verify(String presentedCode, Assignment assignment); } public static final class OtpCredential implements PickupCredential { private final CodeGenerator codeGenerator; public OtpCredential(CodeGenerator codeGenerator) { this.codeGenerator = codeGenerator; } @Override public String issue(Assignment assignment) { return codeGenerator.generate(); } @Override public boolean verify(String presentedCode, Assignment assignment) { return presentedCode != null && presentedCode.equals(assignment.getCode()); } } public static final class Package { private final String packageId; private final SizeClass requiredSize; private PackageStatus status; public Package(String packageId, SizeClass requiredSize) { this.packageId = packageId; this.requiredSize = requiredSize; this.status = PackageStatus.AWAITING_PICKUP; } public String getPackageId() { return packageId; } public SizeClass getRequiredSize() { return requiredSize; } public PackageStatus getStatus() { return status; } void setStatus(PackageStatus status) { this.status = status; } } public static final class Compartment { private final String compartmentId; private final String locationId; private final SizeClass size; private CompartmentStatus status; private Assignment heldBy; public Compartment(String compartmentId, String locationId, SizeClass size) { this.compartmentId = compartmentId; this.locationId = locationId; this.size = size; this.status = CompartmentStatus.AVAILABLE; } public boolean fits(Package pkg) { return this.size.ordinal() >= pkg.getRequiredSize().ordinal(); } // AVAILABLE -> RESERVED. Refuses if not currently AVAILABLE. public void reserve(Assignment assignment) { if (status != CompartmentStatus.AVAILABLE) { throw new IllegalStateException( "Cannot reserve compartment " + compartmentId + " in state " + status); } this.status = CompartmentStatus.RESERVED; this.heldBy = assignment; } // RESERVED -> OCCUPIED. public void occupy() { if (status != CompartmentStatus.RESERVED) { throw new IllegalStateException( "Cannot occupy compartment " + compartmentId + " in state " + status); } this.status = CompartmentStatus.OCCUPIED; } // RESERVED or OCCUPIED -> AVAILABLE. public void release() { if (status != CompartmentStatus.RESERVED && status != CompartmentStatus.OCCUPIED) { throw new IllegalStateException( "Cannot release compartment " + compartmentId + " in state " + status); } this.status = CompartmentStatus.AVAILABLE; this.heldBy = null; } public void markOutOfService() { if (status == CompartmentStatus.OCCUPIED || status == CompartmentStatus.RESERVED) { throw new IllegalStateException( "Cannot take an in-use compartment out of service: " + compartmentId); } this.status = CompartmentStatus.OUT_OF_SERVICE; } public String getCompartmentId() { return compartmentId; } public String getLocationId() { return locationId; } public SizeClass getSize() { return size; } public CompartmentStatus getStatus() { return status; } public Assignment getHeldBy() { return heldBy; } } public static final class Assignment { private final String assignmentId; private final Package pkg; private final Compartment compartment; private String code; private final Instant entryTime; private final Instant expiresAt; private boolean redeemed; private boolean expired; public Assignment(Package pkg, Compartment compartment, Instant now, Duration retention) { this.assignmentId = UUID.randomUUID().toString(); this.pkg = pkg; this.compartment = compartment; this.entryTime = now; this.expiresAt = now.plus(retention); this.redeemed = false; this.expired = false; } public boolean isExpired(Instant now) { return now.isAfter(expiresAt); } boolean isTerminal() { return redeemed || expired; } // At-most-once redeem guard. boolean redeem(Instant now) { if (redeemed || expired) { return false; } if (isExpired(now)) { return false; } this.redeemed = true; this.pkg.setStatus(PackageStatus.PICKED_UP); return true; } // At-most-once expire guard. boolean expire(Instant now) { if (redeemed || expired) { return false; } this.expired = true; this.pkg.setStatus(PackageStatus.EXPIRED); return true; } public String getAssignmentId() { return assignmentId; } public Package getPackage() { return pkg; } public Compartment getCompartment() { return compartment; } public String getCode() { return code; } void setCode(String code) { this.code = code; } public Instant getEntryTime() { return entryTime; } public Instant getExpiresAt() { return expiresAt; } public boolean isRedeemed() { return redeemed; } } public static final class DropOffResult { private final DropOffOutcome outcome; private final String code; private DropOffResult(DropOffOutcome outcome, String code) { this.outcome = outcome; this.code = code; } public static DropOffResult success(String code) { return new DropOffResult(DropOffOutcome.SUCCESS, code); } public static DropOffResult noCapacity() { return new DropOffResult(DropOffOutcome.NO_CAPACITY, null); } public DropOffOutcome getOutcome() { return outcome; } public String getCode() { return code; } } public static final class PickupResult { private final PickupOutcome outcome; private final Compartment compartment; private PickupResult(PickupOutcome outcome, Compartment compartment) { this.outcome = outcome; this.compartment = compartment; } public static PickupResult success(Compartment compartment) { return new PickupResult(PickupOutcome.SUCCESS, compartment); } public static PickupResult of(PickupOutcome outcome) { return new PickupResult(outcome, null); } public PickupOutcome getOutcome() { return outcome; } public Compartment getCompartment() { return compartment; } } public static final class LockerLocation { private final String locationId; private final List compartments; private final Map> freeCompartmentsBySize; // free-compartment index private final Map activeAssignmentsByCode; private final PickupCredential credentialScheme; private final Clock clock; private final Duration retentionWindow; public LockerLocation(String locationId, List compartments, PickupCredential credentialScheme, Clock clock, Duration retentionWindow) { this.locationId = locationId; this.compartments = new ArrayList<>(compartments); this.credentialScheme = credentialScheme; this.clock = clock; this.retentionWindow = retentionWindow; this.activeAssignmentsByCode = new HashMap<>(); this.freeCompartmentsBySize = new EnumMap<>(SizeClass.class); for (SizeClass size : SizeClass.values()) { freeCompartmentsBySize.put(size, new HashSet<>()); } for (Compartment c : this.compartments) { if (c.getStatus() == CompartmentStatus.AVAILABLE) { freeCompartmentsBySize.get(c.getSize()).add(c); } } } // Prove a fitting free compartment exists before touching state. public synchronized DropOffResult depositPackage(Package pkg) { Compartment compartment = findBestFitFreeCompartment(pkg.getRequiredSize()); if (compartment == null) { return DropOffResult.noCapacity(); } Assignment assignment = new Assignment(pkg, compartment, clock.now(), retentionWindow); compartment.reserve(assignment); freeCompartmentsBySize.get(compartment.getSize()).remove(compartment); String code = credentialScheme.issue(assignment); assignment.setCode(code); compartment.occupy(); activeAssignmentsByCode.put(code, assignment); pkg.setStatus(PackageStatus.AWAITING_PICKUP); return DropOffResult.success(code); } // Resolve the reservation by code, run all guards before any mutation, then redeem at most once. public synchronized PickupResult pickup(String code) { Assignment assignment = activeAssignmentsByCode.get(code); if (assignment == null) { return PickupResult.of(PickupOutcome.INVALID); } if (!assignment.getCompartment().getLocationId().equals(this.locationId)) { return PickupResult.of(PickupOutcome.WRONG_LOCATION); } if (!credentialScheme.verify(code, assignment)) { return PickupResult.of(PickupOutcome.INVALID); } if (assignment.isExpired(clock.now())) { return PickupResult.of(PickupOutcome.EXPIRED); } if (!assignment.redeem(clock.now())) { return PickupResult.of(PickupOutcome.ALREADY_REDEEMED); } Compartment compartment = assignment.getCompartment(); compartment.release(); freeCompartmentsBySize.get(compartment.getSize()).add(compartment); activeAssignmentsByCode.remove(code); return PickupResult.success(compartment); } // Sweep assignments past their deadline that are still active, freeing each. public synchronized List reclaimExpired() { List reclaimed = new ArrayList<>(); Instant now = clock.now(); List snapshot = new ArrayList<>(activeAssignmentsByCode.values()); for (Assignment assignment : snapshot) { if (!assignment.isExpired(now)) { continue; } if (assignment.expire(now)) { Compartment compartment = assignment.getCompartment(); compartment.release(); freeCompartmentsBySize.get(compartment.getSize()).add(compartment); activeAssignmentsByCode.remove(assignment.getCode()); reclaimed.add(assignment); } } return reclaimed; } public synchronized int availability(SizeClass size) { return freeCompartmentsBySize.get(size).size(); } // Scan allowed sizes smallest-first. private Compartment findBestFitFreeCompartment(SizeClass requiredSize) { for (SizeClass size : SizeClass.values()) { if (size.ordinal() < requiredSize.ordinal()) { continue; } Set free = freeCompartmentsBySize.get(size); if (!free.isEmpty()) { return free.iterator().next(); } } return null; } public String getLocationId() { return locationId; } } } ::: :::python from __future__ import annotations import uuid from abc import ABC, abstractmethod from datetime import datetime, timedelta, timezone from enum import Enum, IntEnum from typing import Dict, List, Optional, Set class SizeClass(IntEnum): SMALL = 0 MEDIUM = 1 LARGE = 2 XL = 3 class PackageStatus(Enum): AWAITING_PICKUP = "AWAITING_PICKUP" PICKED_UP = "PICKED_UP" EXPIRED = "EXPIRED" RETURNED = "RETURNED" class CompartmentStatus(Enum): AVAILABLE = "AVAILABLE" RESERVED = "RESERVED" OCCUPIED = "OCCUPIED" OUT_OF_SERVICE = "OUT_OF_SERVICE" class PickupOutcome(Enum): SUCCESS = "SUCCESS" INVALID = "INVALID" EXPIRED = "EXPIRED" ALREADY_REDEEMED = "ALREADY_REDEEMED" WRONG_LOCATION = "WRONG_LOCATION" class DropOffOutcome(Enum): SUCCESS = "SUCCESS" NO_CAPACITY = "NO_CAPACITY" class Clock(ABC): @abstractmethod def now(self) -> datetime: ... class SystemClock(Clock): def now(self) -> datetime: return datetime.now(timezone.utc) class CodeGenerator(ABC): @abstractmethod def generate(self) -> str: ... class NumericCodeGenerator(CodeGenerator): def __init__(self) -> None: self._counter = 0 def generate(self) -> str: self._counter += 1 value = (self._counter * 7919) % 1_000_000 return f"{value:06d}" class PickupCredential(ABC): @abstractmethod def issue(self, assignment: Assignment) -> str: ... @abstractmethod def verify(self, presented_code: str, assignment: Assignment) -> bool: ... class OtpCredential(PickupCredential): def __init__(self, code_generator: CodeGenerator) -> None: self._code_generator = code_generator def issue(self, assignment: Assignment) -> str: return self._code_generator.generate() def verify(self, presented_code: str, assignment: Assignment) -> bool: return presented_code is not None and presented_code == assignment.code class Package: def __init__(self, package_id: str, required_size: SizeClass) -> None: self.package_id = package_id self.required_size = required_size self.status = PackageStatus.AWAITING_PICKUP class Compartment: def __init__(self, compartment_id: str, location_id: str, size: SizeClass) -> None: self.compartment_id = compartment_id self.location_id = location_id self.size = size self.status = CompartmentStatus.AVAILABLE self.held_by: Optional[Assignment] = None def fits(self, pkg: Package) -> bool: return self.size >= pkg.required_size # AVAILABLE -> RESERVED. Refuses if not currently AVAILABLE. def reserve(self, assignment: Assignment) -> None: if self.status != CompartmentStatus.AVAILABLE: raise ValueError( f"Cannot reserve compartment {self.compartment_id} in state {self.status}" ) self.status = CompartmentStatus.RESERVED self.held_by = assignment # RESERVED -> OCCUPIED. def occupy(self) -> None: if self.status != CompartmentStatus.RESERVED: raise ValueError( f"Cannot occupy compartment {self.compartment_id} in state {self.status}" ) self.status = CompartmentStatus.OCCUPIED # RESERVED or OCCUPIED -> AVAILABLE. def release(self) -> None: if self.status not in (CompartmentStatus.RESERVED, CompartmentStatus.OCCUPIED): raise ValueError( f"Cannot release compartment {self.compartment_id} in state {self.status}" ) self.status = CompartmentStatus.AVAILABLE self.held_by = None def mark_out_of_service(self) -> None: if self.status in (CompartmentStatus.OCCUPIED, CompartmentStatus.RESERVED): raise ValueError( f"Cannot take an in-use compartment out of service: {self.compartment_id}" ) self.status = CompartmentStatus.OUT_OF_SERVICE class Assignment: def __init__( self, pkg: Package, compartment: Compartment, now: datetime, retention: timedelta, ) -> None: self.assignment_id = str(uuid.uuid4()) self.pkg = pkg self.compartment = compartment self.code: Optional[str] = None self.entry_time = now self.expires_at = now + retention self.redeemed = False self.expired = False def is_expired(self, now: datetime) -> bool: return now > self.expires_at def is_terminal(self) -> bool: return self.redeemed or self.expired # At-most-once redeem guard. def redeem(self, now: datetime) -> bool: if self.redeemed or self.expired: return False if self.is_expired(now): return False self.redeemed = True self.pkg.status = PackageStatus.PICKED_UP return True # At-most-once expire guard. def expire(self, now: datetime) -> bool: if self.redeemed or self.expired: return False self.expired = True self.pkg.status = PackageStatus.EXPIRED return True class DropOffResult: def __init__(self, outcome: DropOffOutcome, code: Optional[str]) -> None: self.outcome = outcome self.code = code @staticmethod def success(code: str) -> DropOffResult: return DropOffResult(DropOffOutcome.SUCCESS, code) @staticmethod def no_capacity() -> DropOffResult: return DropOffResult(DropOffOutcome.NO_CAPACITY, None) class PickupResult: def __init__(self, outcome: PickupOutcome, compartment: Optional[Compartment]) -> None: self.outcome = outcome self.compartment = compartment @staticmethod def success(compartment: Compartment) -> PickupResult: return PickupResult(PickupOutcome.SUCCESS, compartment) @staticmethod def of(outcome: PickupOutcome) -> PickupResult: return PickupResult(outcome, None) class LockerLocation: def __init__( self, location_id: str, compartments: List[Compartment], credential_scheme: PickupCredential, clock: Clock, retention_window: timedelta, ) -> None: self.location_id = location_id self.compartments = list(compartments) self.credential_scheme = credential_scheme self.clock = clock self.retention_window = retention_window self.active_assignments_by_code: Dict[str, Assignment] = {} # free-compartment index self.free_compartments_by_size: Dict[SizeClass, Set[Compartment]] = { size: set() for size in SizeClass } for c in self.compartments: if c.status == CompartmentStatus.AVAILABLE: self.free_compartments_by_size[c.size].add(c) # Prove a fitting free compartment exists before touching state. def deposit_package(self, pkg: Package) -> DropOffResult: compartment = self._find_best_fit_free_compartment(pkg.required_size) if compartment is None: return DropOffResult.no_capacity() assignment = Assignment(pkg, compartment, self.clock.now(), self.retention_window) compartment.reserve(assignment) self.free_compartments_by_size[compartment.size].discard(compartment) code = self.credential_scheme.issue(assignment) assignment.code = code compartment.occupy() self.active_assignments_by_code[code] = assignment pkg.status = PackageStatus.AWAITING_PICKUP return DropOffResult.success(code) # Resolve the reservation by code, run all guards before any mutation, then redeem at most once. def pickup(self, code: str) -> PickupResult: assignment = self.active_assignments_by_code.get(code) if assignment is None: return PickupResult.of(PickupOutcome.INVALID) if assignment.compartment.location_id != self.location_id: return PickupResult.of(PickupOutcome.WRONG_LOCATION) if not self.credential_scheme.verify(code, assignment): return PickupResult.of(PickupOutcome.INVALID) if assignment.is_expired(self.clock.now()): return PickupResult.of(PickupOutcome.EXPIRED) if not assignment.redeem(self.clock.now()): return PickupResult.of(PickupOutcome.ALREADY_REDEEMED) compartment = assignment.compartment compartment.release() self.free_compartments_by_size[compartment.size].add(compartment) del self.active_assignments_by_code[code] return PickupResult.success(compartment) # Sweep assignments past their deadline that are still active, freeing each. def reclaim_expired(self) -> List[Assignment]: reclaimed: List[Assignment] = [] now = self.clock.now() for assignment in list(self.active_assignments_by_code.values()): if not assignment.is_expired(now): continue if assignment.expire(now): compartment = assignment.compartment compartment.release() self.free_compartments_by_size[compartment.size].add(compartment) if assignment.code is not None: self.active_assignments_by_code.pop(assignment.code, None) reclaimed.append(assignment) return reclaimed def availability(self, size: SizeClass) -> int: return len(self.free_compartments_by_size[size]) # Scan allowed sizes smallest-first. def _find_best_fit_free_compartment( self, required_size: SizeClass ) -> Optional[Compartment]: for size in SizeClass: if size < required_size: continue free = self.free_compartments_by_size[size] if free: return next(iter(free)) return None ::: :::: ## 6. Extensibility and Tradeoffs With deposit and pickup working, extensions should land in a focused part of the design and leave unrelated lifecycle owners untouched. The following cases show where each change belongs. ### Add a new size class Size is data rather than behavior. Adding a `SUPER_XL` compartment, or allowing best-fit to fall back to a larger free size, only requires a new enum value plus corresponding index and allocator ordering. ```js enum SizeClass: SMALL MEDIUM LARGE XL SUPER_XL // [new] Ordered last ``` `Compartment`, `Package`, `Assignment`, and `PickupCredential` are all untouched. Size differs only by data, so it remains an enum with an ordering. No new pattern is needed, and fallback to a larger compartment only changes how the location scans the index. ### Swap the allocation policy Choosing which compartment to allocate is separate from the mechanics of reserving it. Supporting first-fit or wear-balancing alongside best-fit introduces real policy variation, so an `AllocationStrategy` now has multiple behaviors to represent. At baseline there was only one selection rule, so an interface would have been premature. ```js class LockerLocation: - allocationStrategy: AllocationStrategy // [new] Injected seam depositPackage(pkg) compartment = allocationStrategy.select(pkg, freeCompartmentsBySize) if compartment == null return DropOffResult.noCapacity() // Reserve and issue handoff remains unchanged ``` `LockerLocation` stays the stable call site and delegates only the selection. The crucial constraint is that the strategy reads the index and returns a candidate but never mutates compartment state, so the guarded reserve-and-issue handoff is byte-for-byte unchanged. `Compartment`, `Assignment`, and `PickupCredential` do not move: policy variation without touching the safety-critical handoff. ### Support a different credential scheme Barcodes or app tokens can replace the numeric OTP without changing deposit or pickup because generation and verification already sit behind `PickupCredential`. ```js class BarcodeCredential: + issue(assignment: Assignment) -> String // Returns a barcode payload + verify(presentedCode: String, assignment: Assignment) -> boolean ``` Add the implementation and inject it. `LockerLocation`'s deposit and pickup flows, `Compartment`, `Package`, and `Assignment` remain unchanged. Expiry and redemption state live on `Assignment`, so changing how a code is represented cannot disturb the at-most-once invariant. A standalone `AccessCode` entity would have mixed this reservation lifecycle with the replaceable credential format. ### Handle concurrent claims and redemptions The baseline should start with the simplest concurrency guarantee its code actually provides. The shared mutable state is compartment status and the redeemed or expired state on the assignment. The races are two deposits claiming one compartment, or a redemption overlapping another terminal transition. Start simple: make `depositPackage` and `pickup` synchronized on the location, so no two callers interleave inside a check-then-act sequence at all. ```js class LockerLocation: + synchronized depositPackage(pkg) -> DropOffResult + synchronized pickup(code) -> PickupResult ``` That is correct and is the guarantee the Java reference implementation provides. Narrower synchronization around the owned transitions is a possible refinement, but it is not required for the baseline model. The class model does not change either way: the choice is how broadly to serialize access to the same owned state, not whether to introduce new domain abstractions. ### Reclaim with a background sweeper A background sweeper changes who triggers reclamation, not how reclamation works. Expiry is currently checked lazily on access or through a manual `reclaimExpired` call; a sweeper can periodically invoke that same method. ```js class ExpirySweeper: - location: LockerLocation - clock: Clock + runOnce() -> void // Calls location.reclaimExpired() ``` Both the lazy on-access check and the sweeper funnel through the same legal release transition, so no new lifecycle code is added and `Compartment`, `Package`, `Assignment`, and `PickupCredential` are untouched. This stays clean because reclamation was already modeled as the same guarded transition as a normal release: the sweeper is just a second trigger for an operation that already existed, not a parallel code path that could drift. ## 7. Interviewer Expectations ### Junior A junior candidate produces the right four classes without much prompting: a `LockerLocation` that holds compartments, a `Compartment`, a `Package`, and some notion of a reservation, with `depositPackage` and `pickup` methods. They handle the two obvious cases, no free compartment and a wrong code, often with a boolean return. Where they typically need hints is the lifecycle: they may leave occupancy as a flag the location flips, store the code on the package, and treat pickup as a single happy path that mutates state before checking. If you can name the four classes, allocate by size, and issue and check a one-time code, you are in good shape for this level. ### Intermediate An intermediate candidate gets the state ownership mostly right on their own. They put occupancy on the compartment, recognize that the reservation deserves its own record rather than flags scattered across the package, and run the full set of failure checks before mutating any state. They compute expiry from a clock rather than a hardcoded call, and keep the free-compartment lookup as an index on the location. They usually still need a nudge to articulate why the redeemed flag belongs on the reservation, and to see that the lazy expiry check and a sweeper should converge on one transition. The clearest signal at this level is guard-before-mutate discipline plus a typed pickup result. ### Senior A senior candidate surfaces the central tension without being asked: two things must each happen exactly once under concurrency, a compartment handed to one package and a code redeemed once, and the naive check-then-act flags lose that guarantee the moment two actors overlap. They state the intrinsic-vs.-relational split out loud, occupancy intrinsic to the compartment and the one-time-code state intrinsic to the assignment, and they explain that this split gives the design one clear home for each guard. They reason about concurrency by starting from the simplest correct lock and then, if needed, discussing finer granularity as a later refinement; they catch the redeem-vs.-sweep race, and they place exactly the earned seams while refusing to over-engineer with a standalone code entity or size subclasses. The clearest senior signal is naming the two at-most-once invariants and showing how the ownership split supports a correct baseline implementation without pretending the model alone provides stronger concurrency guarantees than the code actually adds.