- 1. Register shipment
- 2. Normalize milestones
- 3. Detect missing update
- 4. Review delivery evidence
- 5. Close exception
The business scenario
A logistics coordinator receives tracking updates through carrier APIs, spreadsheets and email attachments. Customers ask for status while staff manually locate proof-of-delivery documents. The proposed portal consolidates milestones and evidence while showing when information is incomplete or stale.
A practical first release
Cover one shipper organization, two carrier adapters and a limited milestone vocabulary: booked, collected, in transit, out for delivery and delivered. Customers see only their own shipments. Operations staff can inspect raw carrier updates, attach approved delivery evidence and assign exceptions. Route optimization, driver surveillance and guaranteed arrival predictions are outside scope.
How the workflow would operate
A shipment is registered with the carrier reference and customer ownership. Adapters receive webhooks or poll approved endpoints, preserve the original event and map it to a normalized milestone. The portal displays both event time and last synchronization time. Missing updates or a delivered event without required evidence enter an operations queue.
Architecture and integrations
A responsive portal would use an API layer for customer authorization and shipment queries. PostgreSQL would store shipment relationships, milestones and exception ownership. Documents would live in private storage accessed through short-lived authorized links. Independent carrier adapters would isolate provider changes and apply rate limits and retries.
Handling imperfect information
Carrier systems disagree on status names and time zones. The design preserves raw data alongside normalized values and distinguishes estimated dates from confirmed events. Late events can enrich the history without incorrectly moving a delivered shipment backwards. Staff amendments require a reason and remain distinguishable from carrier-supplied information.
Evaluation plan
Test duplicate milestones, out-of-order updates, daylight-saving boundaries, unavailable carriers and mismatched tracking references. Confirm that a customer cannot access another customer's shipments or documents. Measure update freshness and exception age during a pilot. The portal must explain missing data instead of presenting an unsupported delivery promise; this concept has no measured client outcomes.
Delivery and next steps
The proposed package includes the customer portal, operations queue, two adapters, document access rules, synchronization monitoring and recovery instructions. Begin with read-only visibility, validate timelines against carrier records, then introduce controlled document and exception workflows.