Design an Amazon Locker Service

Scenario

Design the core software architecture and domain model for an automated self-service package locker station (e.g., Amazon Hub Locker). The kiosk contains a fixed set of physical compartments of varying sizes and serves both couriers, customers, and return/maintenance staff.

Requirements

Functional Requirements

• Compartment Allocation: The station contains compartments in fixed sizes (SMALL, MEDIUM, LARGE, EXTRA_LARGE). When a package arrives, assign it to the smallest available compartment that fits the package dimensions.
• Customer Pickup Code: Depositing a package generates a secure, one-time pickup code valid for exactly 7 days.
• Customer Pickup Workflow: Entering a valid, unexpired code unlocks the corresponding compartment door. When the door is closed, the pickup is completed and the compartment becomes available.
• Expiration Workflow: If 7 days elapse without pickup, the access code expires. The parcel state transitions to expired, but the compartment must not be marked available for new deposits until the package is physically removed.
• Staff Clearance: Station staff must be able to view and unlock expired compartments, physically extract the package, and explicitly submit a removal confirmation to release the compartment back to the available pool.

Non-Functional Requirements

• State Integrity: A pickup code expiring or being invalidated must never prematurely release a compartment while an item remains inside.
• Concurrency: Prevent race conditions where two couriers attempt to allocate the same physical compartment simultaneously.

What to Cover

1. Class Design & Domain Entities: Define key classes (e.g., LockerStation, Compartment, Package, AccessTicket, StaffService).
2. State Modeling: Define clear state transitions for both Compartment (e.g., AVAILABLE, RESERVED, OCCUPIED, PENDING_CLEARANCE) and Package (e.g., DEPOSITED, RETRIEVED, EXPIRED, RETURNED_TO_DEPOT).
3. API & Workflow Methods: Provide class signatures and step-by-step logic for:
   • allocateAndDeposit(packageDetails)
   • pickup(code)
   • expireTicket(ticketId)
   • clearExpiredCompartment(staffId, compartmentId)
4. Edge Cases: Handle sensor failures (e.g., door opened but closed without package removal) and code expiration while customer is in front of the kiosk.