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 /eventsingests one JSON scan:
{
"eventId": "evt-02",
"shipmentId": "DEMO-101",
"occurredAt": "2026-01-15T10:20:00Z",
"status": "DELIVERY_EXCEPTION",
"exceptionCode": "ADDRESS_ISSUE"
}eventIdandshipmentIdare nonblank strings with no leading/trailing whitespace;occurredAtis a real UTC timestamp in exactlyYYYY-MM-DDTHH:MM:SSZform;statusis one ofIN_TRANSIT,DELIVERY_EXCEPTION,DELIVERED.exceptionCodeis a required nonblank string forDELIVERY_EXCEPTIONand must be absent for other statuses. Ignore any unrelated fields.eventIdis globally unique. First ingest returns201; an identical replay of the sameeventIdreturns200and stores no second row; reusing the ID with any changed event field returns409and leaves the original untouched. Both successful responses return the event.- Malformed JSON or any invalid field returns
400before any state changes. - An event implicitly creates its shipment.
GET /shipments/{shipmentId}returns200with{shipmentId, status, events}: every accepted event, newest byoccurredAtfirst, timestamp ties broken by ascendingeventId;statusis 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 /exceptionsreturns200with a JSON array of the latest events of shipments currently inDELIVERY_EXCEPTION, sorted by ascendingshipmentId;[]when none qualify. A newerDELIVEREDclears the exception; replaying an older event does not reopen it. Reads reflect completed writes immediately.
- Errors are JSON with
errorequal toinvalid_event(400),event_id_conflict(409) orshipment_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:
POST /eventswithevt-02at10:20:00Z,DELIVERY_EXCEPTION,exceptionCodeADDRESS_ISSUE→201.POST /eventswithevt-01at10:00:00Z,IN_TRANSIT→201(a late scan). History is[evt-02, evt-01]andGET /exceptionscontainsevt-02.- Repeat
evt-02unchanged →200, still two events. - Reuse
evt-02asDELIVEREDwithoutexceptionCode→409, nothing changes. POST /eventswithevt-03at10:35:00Z,DELIVERED→201. History is[evt-03, evt-02, evt-01], current status isDELIVERED, andGET /exceptionsis[]— also after a restart.
Acceptance criteria
- Automated tests cover: the worked example above; same-timestamp tie-breaking by
eventId;400on invalid input with no writes;404for 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.mdthat 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 ./...orcargo 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.