Problem statement
Design the object model and core APIs for a returns system that validates return requests, issues return authorizations (RMAs), and tracks returned items from receipt through inspection to resolution, for a single retailer.
Operating context. A customer requests the return of some line items from a past order. Policy rules decide, per line, whether the item is eligible (within the return window, an allowed condition/category, not marked final-sale). Eligible lines get an RMA with return instructions and a tracking identifier. As items arrive they are inspected, and each line receives a resolution: refund, replacement, store credit, or rejection. A multi-line order may be returned partially and across several RMAs over time. Requests for different orders may be processed concurrently, and the whole thing is a single in-process service.
Out of scope. Shipping-label generation, the actual refund/credit execution (place it behind a port), the original checkout/order service, the warehouse WMS, and customer notifications.
What to produce. The class hierarchy (ReturnRequest, ReturnLineItem, the policy/eligibility rules, RMA, Inspection, Resolution types, ReturnService facade), the public API each exposes, the RMA lifecycle states, and the eligibility-rule model. Be explicit about: how a new eligibility rule is added without editing the evaluator, how partial and repeated returns respect the originally purchased quantity, and how per-line resolutions are chosen and applied.
Functional requirements
- Evaluate a return request against policy rules to decide, per line item, whether it is eligible.
- Issue an RMA for the eligible lines with return instructions and a tracking identifier.
- Advance the RMA through its lifecycle as items are received and inspected.
- Choose a per-line resolution (refund, replacement, store credit, or rejection) from the inspection outcome.
- Support partial returns, so a multi-line order can have several independent RMAs over time.
Non-functional requirements
- Eligibility evaluation is O(rules x lines) with no scan of unrelated orders.
- Policy rules are pluggable; a new rule (e.g. a hazardous-item block) adds a class without editing the evaluator.
- The RMA lifecycle is a total state machine; illegal transitions are rejected, not silently ignored.
- Refund/replacement effects sit behind ports, so resolutions are unit-testable without external systems.
- Quantities are conserved: returned lines across all RMAs never exceed the originally purchased quantity.
- The model is deterministic under an injected clock, since the return window depends on it.
Topics
- System Design LLD
- Commerce Returns
- Patterns State
- Patterns Strategy
- Oop Solid