You're joining the returns team for a day. We run the customer-facing returns portals for many well-known brands. Customers use them to look up an order, see which items are eligible for return, and submit a request. You may have used one yourself. The portal is live, but it's rough around the edges: the previous engineer left before finishing some critical backend work, tests are failing, and a few things are broken.
Below is the current backlog. The first three tasks (BR-001–003) are required; you
don't have to do everything else — pick the electives that best show what you can do,
and explain your choices in DECISIONS.md.
Please do not fork this repository. Clone it directly, work locally, and submit a personal repository on GitHub, GitLab, or Codeberg, or send us a zip file.
Stack: Python 3.12+, Django, pytest, Ruff, mypy. PyYAML is included if you want it for rules config.
uv sync
uv run pytest # you'll see some failures — that's intentional
uv run python manage.py runserverOpen http://localhost:8000/returns/ and try order RMA-1001 with email
alex@example.com or zip 10115.
portal/
data/orders_raw.json # raw order payloads from upstream
data/ # your rules config goes here (you define the format)
services/mapper.py # maps raw payload → domain model (incomplete)
services/eligibility.py # return eligibility evaluator (stubbed)
templates/returns/* # Django + HTMX UI
tests/* # pytest suite (some tests intentionally failing)
Time budget: ~4 hours. Document your decisions, prioritization, and skips in
DECISIONS.md.
AI tools are welcome. If you use them, note which tools you used and what for in
AI_LOG.md.
BR-001, BR-002, and BR-003 are required. We use those three to compare submissions.
Everything else is an elective: pick one or two, skip the rest, and explain your choices
in DECISIONS.md.
Our upstream order system sends detailed payloads, but the mapper was left unfinished — item-level flags never got wired up. The eligibility engine needs these to make decisions.
Missing fields on each article:
is_digitalis_final_salecategory
Look at the raw data in orders_raw.json and the test fixtures to understand the
different payload shapes you need to handle.
Right now, evaluate_eligibility() just marks everything as returnable. We need a real
rules engine — one that's configurable, not hardcoded.
Design your own rules format (JSON, YAML, whatever you prefer) and implement the evaluator. It should return a clear result per item (returnable or not, reason, matched rule) and handle at least:
- Return window (delivered date + allowed days)
- Already fully returned
- Digital items
- Final-sale items
Policies vary per brand and change more often than code ships. Real requests we've seen:
"final sale is returnable for VIP customers", "digital is non-returnable except gift
cards", "stricter windows in some markets". Don't implement these — but in
DECISIONS.md, tell us which your design handles via config, which need code, and why
that's the right line.
We intentionally don't provide a rules file — we want to see how you'd structure it.
Several tests are failing. Some depend on BR-001 and BR-002 being done, others may have their own issues. Make the suite green and add tests that give you confidence in your implementation.
Product just told us that different categories need different return windows. Electronics should be 14 days, apparel gets 30, and so on. Add per-category window config to the rules engine and make the evaluator use it. Fall back to the order-level default when a category isn't configured.
A security researcher claims they can read any customer's order data — and wants money for the details. Find the vulnerability, fix it, and prove the fix with a test.
If you spot other weaknesses in how customers authenticate here, note them briefly in
DECISIONS.md or SECURITY.md — no need to fix them.
Support keeps asking: can customers filter the articles list to only see what's actually returnable? Add a "Show returnable only" toggle using HTMX — no full page reload.
The "Continue" button on the articles page is dead — the rest of the flow was apparently deleted before the last push. Build the missing pieces: article selection → confirmation → success. A customer should be able to complete a return end-to-end, and a submitted return must survive a server restart — persist it.
One thing support keeps seeing: impatient customers double-click submit, or hit refresh on the success page. Decide what should happen in both cases and implement it.
If you spot another useful improvement, you can take it on. Keep it small and describe
it in DECISIONS.md.
- Working, type-safe code
- Small, readable commits
DECISIONS.md— what you picked, what you skipped, and whyAI_LOG.md— if you used AI tools
© parcelLab