API servicehard

Shipment tracking and delivery exceptions API

Build a shipment tracking API that handles duplicate and late scans and shows dispatchers which deliveries need attention.

Suggested effort
~5h focused work
Window
24 hours
Starts from
An empty repo
Stack
Your choice
Sign in to start this build →

Opens in a new tab. The clock starts when you press Start inside the environment, not before, and your workspace is kept while you step away.

Time window 24 hours. Suggested effort about 5 hours.

Context

A fictional regional carrier runs deliveries across a few cities. Support agents need a reliable tracking history per shipment, and dispatchers need a live list of shipments with unresolved delivery exceptions (wrong address, recipient absent, damaged parcel) so they can act before the delivery window closes.

Scanners in vans and depots are unreliable: the same scan is often sent twice, scans arrive out of order, and a "delivered" scan can land hours after an exception was reported. The tracking API must stay correct under all of that.

This exercise is inspired by a public Coderio case study about modernising a real-time shipment tracking platform. It is an original hiring exercise: every event here is synthetic, the carrier is fictional, and no Coderio or FedEx systems, data or client requirements are involved.

Core requirements

  • POST /events ingests one JSON scan:
  {
    "eventId": "evt-02",
    "shipmentId": "DEMO-101",
    "occurredAt": "2026-01-15T10:20:00Z",
    "status": "DELIVERY_EXCEPTION",
    "exceptionCode": "ADDRESS_ISSUE"
  }
  • eventId and shipmentId are nonblank strings with no leading/trailing whitespace; occurredAt is a real UTC timestamp in exactly YYYY-MM-DDTHH:MM:SSZ form; status is one of IN_TRANSIT, DELIVERY_EXCEPTION, DELIVERED.
  • exceptionCode is a required nonblank string for DELIVERY_EXCEPTION and must be absent for other statuses. Ignore any unrelated fields.
  • eventId is globally unique. First ingest returns 201; an identical replay of the same eventId returns 200 and stores no second row; reusing the ID with any changed event field returns 409 and leaves the original untouched. Both successful responses return the event.
  • Malformed JSON or any invalid field returns 400 before any state changes.
  • An event implicitly creates its shipment.
  • GET /shipments/{shipmentId} returns 200 with {shipmentId, status, events}: every accepted event, newest by occurredAt first, timestamp ties broken by ascending eventId; status is that first event's status. An older event received later appears in the history without overriding the current status — the newest event wins, with no separate transition state machine. Unknown shipment: 404.
  • GET /exceptions returns 200 with a JSON array of the latest events of shipments currently in DELIVERY_EXCEPTION, sorted by ascending shipmentId; [] when none qualify. A newer DELIVERED clears the exception; replaying an older event does not reopen it. Reads reflect completed writes immediately.
  • Errors are JSON with error equal to invalid_event (400), event_id_conflict (409) or shipment_not_found (404).
  • Accepted events, their ordering and replay handling survive a service restart, using local storage.

Worked example

For shipment DEMO-101 on 2026-01-15 (all times UTC), in this order:

  1. POST /events with evt-02 at 10:20:00Z, DELIVERY_EXCEPTION, exceptionCode ADDRESS_ISSUE → 201.
  2. POST /events with evt-01 at 10:00:00Z, IN_TRANSIT → 201 (a late scan). History is [evt-02, evt-01] and GET /exceptions contains evt-02.
  3. Repeat evt-02 unchanged → 200, still two events.
  4. Reuse evt-02 as DELIVERED without exceptionCode → 409, nothing changes.
  5. POST /events with evt-03 at 10:35:00Z, DELIVERED → 201. History is [evt-03, evt-02, evt-01], current status is DELIVERED, and GET /exceptions is [] — also after a restart.

Acceptance criteria

  • Automated tests cover: the worked example above; same-timestamp tie-breaking by eventId; 400 on invalid input with no writes; 404 for an unknown shipment; and persistence of history and exception state across a service restart.
  • The whole test suite runs with one command and is CI-ready.
  • The README includes copy-pasteable run and test commands, the replayable synthetic example, and an explanation of the event-time ordering and replay decisions.

Stretch goals (optional)

  • A CI workflow that runs the test suite.

Constraints

  • Any workspace-compatible stack; suggested: Python or Node.js with SQLite. Keep the service and tests self-contained: no cloud accounts, credentials, message brokers, live carrier integrations, UI, or streaming transport. The workspace ships Python and Node.js tooling; do not require a JDK or Maven.
  • All data is synthetic; do not use any real carrier data, branding or customer names.

Deliverables (every project)

  • Source code committed in this repository (the grader diffs against the first commit).
  • README.md that replaces the stub, with: how to install, run and test it (copy-pasteable commands); the decisions and trade-offs you made; what you would do next with more time; and a short note on how you used the AI agent (what you delegated, what you checked or rewrote).
  • Automated tests that run with a single command (npm test, pytest, go test ./... or cargo test).
  • No secrets in the repository. Anything configurable reads from environment variables with safe defaults.

Ground rules

  • The 24-hour clock is a window, not a workload. Stop at roughly the suggested effort, then write down what you would do next. A small, finished, tested core beats a large unfinished one.
  • Use the AI agent as much or as little as you like: every prompt is recorded and the report shows how it was used. You are judged on the result and on whether you understood and verified what the agent produced.
  • The work is yours. PraxisAI uses it only to produce your assessment report.
Shipment tracking and delivery exceptions API: a 24-hour take-home project | PraxisAI