Multi-leg Shipments

Documents belong to legs,
not just shipments.

A real import move is factory → export drayage → origin port → main vessel → (transshipment) → destination port → import drayage → DC. Qubere models it as one canonical leg structure both apps read from — with a per-leg document checklist, rule-based route inference from the paperwork, and a journey ribbon that never collapses the whole thing into one status.

1
canonical leg model · customs + freight read the same rows
rules-v1
deterministic inference · never invents a carrier

Phase 1 shipped (PR #107). Not in scope: real-time carrier-tracking integrations, last-mile parcel legs, converging the TMS freight-ops movement model onto ShipmentLeg.

The problem

The document library is one flat pile, and the ribbon flattens the journey.

"It can't tell me 'the ocean leg is missing its master bill' vs 'the import leg is missing its delivery order' — it's one pile linked to the shipment."

No per-leg docs

"The customs team and the freight team show different leg counts for the same container — different pipelines, never reconciled."

Two leg models

"The ribbon says 'Arrived.' The import drayage hasn't started. And 'arrived at port' is not 'released by customs.'"

Flattened status

How Qubere addresses it

One leg model. Per-leg documents. A ribbon that never lies.

  • ShipmentLeg is the single source both apps read. One shipmentId stays the durable end-to-end identifier — legs hang off it, never fragment it.
  • A ShipmentLegDocument join: one document can belong to one or more legs; shipment-level documents stay at the shipment.
  • Rule-based inference proposes leg count, mode, endpoints, and the per-leg document checklist — the broker confirms.
  • Three status levels that never contradict: leg (physical), movement rollup (derived), customs clearance (independent rail).

The journey ribbon

A leg that's arrived, next to a leg that hasn't started — both visible.

The full end-to-end route: per-leg status, per-leg document completeness, per-leg ETA. No collapsing a multi-leg shipment into one status. And the customs rail is independent — an arrival never implies a release.

  • Movement rollup is derived, never a hand-maintained field
  • The journey ribbon lives on the Shipments detail page; the TMS lifecycle status reads the same leg rows
How to demo
Open SHP-TGT-2026-001 — the ribbon. Point at the movement rail ("Arrived") and the customs rail ("In review") side by side.
Shipments/SHP-TGT-2026-001
JT
Joe · Target
Journey
Drayage
Factory → Yantian
Complete
Ocean
Yantian → LA/LB
Arrived · MBL only
Rail
LA → KC
Not started
Drayage
KC ramp → DC
Not started
Movement rollup
Arrived (dest port)
Customs rail
In review — not released

Per-leg document checklists

"Which leg is missing which document" is answerable at a glance.

Each leg has stable document slots — booking confirmation, shipping instructions on the export leg; master bill on the ocean leg; arrival notice, delivery order on the import leg; POD on the final leg. One document can fill a slot on more than one leg.

  • Slot identity is stable even though the docs all map to DocumentType.OTHER
  • Attach with a real document picker from the shipment's library
How to demo
On the ribbon, expand the ocean leg → its checklist with filled and empty slots. Attach the MBL to a slot.
SHP-TGT-2026-001·Ocean leg
JT
Joe · Target
Document slots
Master Bill of Lading✓ mbl_yantian.pdf
Shipping Instructions✓ (shared w/ export leg)
Arrival Noticemissing · attach
Delivery Ordermissing
ShipmentLegDocument · @@unique([legId, slotKey])

Rule-based route inference

The route infers itself from the paperwork you already have.

From the documents on a shipment, Qubere proposes leg count, mode, endpoints, sequence, and the per-leg document set. Deterministic (rules-v1), idempotent (keyed on a SHA-256 of the inputs), and it never invents a carrier or vessel it can't derive — those stay null for the broker to confirm.

  • The proposal is a diff you accept or edit — never a silent commit
  • Accept → legs created transactionally, re-sequenced safely
How to demo
On a shipment with documents, the inference proposal card appears on the journey ribbon → review the proposed changes → Accept (or Reject).
SHP-2026-000209·Infer legs
JT
Joe · Target
Proposed legs (3)
1 · DrayageNingbo factory → Ningbo port · carrier: null (confirm)
2 · OceanNingbo → Long Beach · carrier: Maersk (from MBL)
3 · DrayageLong Beach → Ontario DC · carrier: null
Doc checklist derived14 slots across 3 legs

Why this is the "tech advanced" story

"Arrival is not release" is a correctness stance, not a slogan.

The independent customs rail means the ribbon will never let "arrived at port" masquerade as "cleared." For a customer running Qubere for customs and freight, the leg count is the same on both sides — because it's the same data. Most competitors keep two disagreeing models and a status that lies.

Objection handling

Every hard question, answered directly.

"Do you integrate with carrier tracking / ocean visibility?"Not in this phase. Inference and the ribbon consume whatever tracking events already arrive on the shipment. Adding visibility providers is a defined next step, not a current capability.
"How accurate is the inference?"Deterministic rule logic, not a model. It proposes structure and checklists from document types, port pairs, and reference numbers, and is conservative — anything it can't derive is left blank for you. A head-start, not an autopilot.
"Can one container split into multiple downstream shipments?"Sub-shipment splitting / one-to-many is explicitly a non-goal for now.

The close

"One leg model, both apps. Documents belong to legs. And the ribbon never tells you 'cleared' when it isn't."

Next step: bring a recent multi-leg move with its document set. We run the inference live and you check the proposed route and checklist against reality.

Full detail: docs/apps/tms/sales/multi-leg-shipments.md