Cross-border cargo custody and tracking

The problem

Consolidated freight is a custody problem wearing a logistics costume. Hundreds of individual customer packages are packed into a single sea container in one country and pulled apart again in another. Between those two moments, every package has to remain individually identifiable — because each one belongs to a different person who will, eventually, ask where it is.

This client ran that operation across two countries with no shared system. The Singapore counter registered packages and built containers. Package details were then emailed to the Manila office, where staff re-keyed them by hand into their own records. From there, movement was tracked on paper.

Every part of that is a failure waiting for a busy week. Re-keying introduces transcription errors into the one field that matters — whose box is this. Email is not a database: there is no single answer to “where is package X”, only somebody’s most recent message about it. Paper tracking cannot be queried, cannot be audited, and cannot tell a customer anything. When something went missing, reconstructing its history meant phone calls between offices and a search through inboxes.

The cost of this is not mainly staff time, though that is real. It is that the business could not answer its customers’ only question with confidence.

What we built

One shared system spanning both countries, with the package — not the container, and not the office — as the unit of truth.

A seven-stage custody flow, plus the exceptions. Every package moves through an explicit seven-stage happy path — and twenty states in total, because lost, damaged, on-hold, failed-attempt and returned-to-office are real outcomes that a system pretending otherwise just loses track of. Every package moves through an explicit lifecycle, and each transition is a recorded event with a time, a place and a person attached. Status is not a field somebody edits; it is the consequence of a scan that actually happened. This is the difference between a system that describes reality and one that merely stores opinions about it.

QR-driven scanning. Packages carry a QR code from intake. Warehouse and driver staff scan rather than type, which removes the re-keying step that was generating the errors in the first place. The scan interfaces are built for phones held in one hand in a warehouse, not for desks.

Photographic proof of delivery. The final custody transition captures an image. A delivery dispute stops being one person’s word against another’s.

Surfaces shaped to each job. A counter interface for Singapore intake and container building. An operations view for Manila to track inbound containers, sort to regions and dispatch to drivers. Phone-oriented scan screens for warehouse staff in both countries. A mobile app for drivers. A public tracking portal for customers, built mobile-first because that is where a customer checks on their shipment — and a public booking flow for senders.

Resilience as a requirement, not a feature. Warehouses and delivery routes have unreliable signal. The scanning surfaces are built to tolerate losing connectivity mid-shift and to recover cleanly rather than silently dropping a custody event. In a custody system, a lost scan is worse than a failed one, because a failure is visible.

Why it was built this way

Roles are enforced in the database, not the interface. Singapore staff, Manila staff, drivers, warehouse crew, supervisors and administrators each see a different system. Those boundaries live in Postgres row-level security, so they hold whether a request arrives from the web app, the mobile app or anywhere else. Access control implemented only in a UI is a suggestion.

Identity is verified, because the customer base is international. The platform verifies customers using national identity numbers. That sounds like a compliance detail; it is actually what makes serving a diaspora customer base workable rather than a permanent support burden.

It runs on the edge. The application is served from Cloudflare’s global network, which matters when your customers and your two offices are in different countries and none of them should be waiting on a round-trip to a server somewhere else.

The schema is treated as the product. More than eighty reversible migrations have shipped against this database. Custody systems accrete rules — new stages, new exceptions, new pricing — and a schema that cannot evolve safely becomes the thing that stops the business changing.

The result

The two offices work from one record instead of two, and nothing is re-keyed between them. Where a package is, and where it has been, is a query rather than a phone call. Customers can see their own shipment without contacting anyone. Delivery is evidenced.

The system has been live in production through more than eighty schema revisions, with an automated test suite gating every release — unit, database-level and browser-driven journey tests, with a coverage report that fails the build when it slips.

It is also the reference deployment behind our work on deterministic AI for freight operations: the domain fluency in this platform is what makes it possible to build an assistant for this industry that cannot invent an answer.