Logistics & Shipping

Why this is an orchestration problem, not a tracking problem

A shipment touches warehouse staff, carriers, recipients, finance, and customer service — each with a different view of the same record and different authority to act on it. Coordinators dispatch; operations teams pick up and deliver; finance sees freight costs that floor staff should not; exceptions escalate only when SLA thresholds are breached. Stitching this together across spreadsheets and phone calls is how shipments get lost and freight costs balloon undetected.

AuraBoot's logistics plugin encodes the full lifecycle as a state machine, gates every transition behind a permissioned command, and emits audit records and events that downstream finance and customer-service modules consume — no custom code required.

Shipment lifecycle

  [created / draft]
        |
        | lg:confirm_shipment
        v
  [confirmed]
        |
        | lg:pickup_shipment  (requires tracking number)
        v
  [picked_up]
        |
        +------ tracking events logged (in_transit, arrived_hub, ...) ------+
        |                                                                    |
        | lg:deliver_shipment                               exception event  |
        v                                                         v
  [delivered]                                              [exception]
        |
        | lg:sign_delivery_note
        v
  [delivery note signed]

  (draft or confirmed) --- lg:cancel_shipment ---> [cancelled]

Every node maps to a command. No status update can bypass the command pipeline — a raw PUT to lg_shipment cannot drive a state transition.

Data model summary

The plugin ships four cooperating models:

log_carrier — Master registry of freight partners; stores service type (express, standard, freight, air, sea), contact info, and tracking URL template.
log_shipment — The primary document; auto-generated code LG-{yyyyMMdd}-{seq}; status enum draft → confirmed → picked_up → in_transit → delivered / exception / cancelled; carries log_sh_freight_cost for reconciliation and log_sh_source_order_id to trace back to any originating sales or purchase order.
log_tracking_event — Append-only milestone log per shipment: created, picked_up, in_transit, arrived_hub, out_for_delivery, delivered, exception, returned.
log_delivery_note — Proof-of-delivery document; auto-generated code DN-{yyyyMMdd}-{seq}; status pending → signed / disputed; captures recipient and signed-by fields.

log_shipment declares documentConfig.lineModel: log_shipment_line, so line items (product, qty, weight, lot number) aggregate automatically into log_sh_total_qty on the header.

Key commands

Command	Type	From state	To state
`log.shipment.create`	create	—	`draft`
`log.shipment.confirm`	state	`draft`	`confirmed`
`log.shipment.pickup`	state	`confirmed`	`picked_up`
`log.shipment.deliver`	state	`picked_up` / `in_transit`	`delivered`
`log.shipment.cancel`	state	`draft` / `confirmed`	`cancelled`
`log.shipment.dispatch`	action	`confirmed`	assigns lane + carrier
`log.tracking.append`	create	—	new `log_tracking_event` row
`log.delivery_note.sign`	state	`pending`	`signed`

log.shipment.dispatch is the lane-scoped command: it writes the carrier assignment and records which dispatch agent acted. log.tracking.append is the append-only event logger — idempotent per (shipment_id, event_type, event_time).

Permission example

A realistic logistics role spans all five permission layers:

RBAC (Layer 1): Dispatch Agent holds log.shipment.dispatch and log.tracking.append; does not hold log.shipment.deliver (held by field operations).
Org scope (Layer 3): Dispatch Agent's data visibility is filtered to their assigned lane (lane_id IN agent_lanes). A coordinator in the north-China lane cannot see or act on south-China shipments.
Field mask (Layer 5): log_sh_freight_cost is visible to Finance and Coordinator roles only. Operations staff see the field slot as blank — the value is not returned by the API for their token.
ABAC (Layer 4): Exception escalation via log.shipment.escalate is only permitted when hours_since_exception >= sla_threshold evaluated at command execution time. Below the threshold, the button renders disabled regardless of role.

All four layers are declared in the plugin's permissions.json and bindingRules.json. No controller branching required.

Process flow

  Warehouse confirms pick-and-pack
        |
        | log.shipment.create + log.shipment.confirm
        v
  Carrier assigned (log.shipment.dispatch)
        |
        | log.shipment.pickup  [tracking number required]
        v
  Tracking events appended  (log.tracking.append loop)
        |
        | log.shipment.deliver
        v
  Delivery note created + signed  (log.delivery_note.sign)
        |
        | freight cost reconciled against carrier invoice
        v
  Finance closes shipment cost record

Source order linkage (log_sh_source_order_id) lets the finance module join shipment freight costs back to sales or purchase orders without any custom join logic — the field is indexed and searchable from the shipment list page.

Agent integration

Three command classes are intentionally exposed to AI agents in this solution:

Read commands (log.shipment.list_overdue, log.tracking.latest) — read-only, idempotent, low risk.
Append commands (log.tracking.append) — write, idempotent per event identity. An agent monitoring carrier API webhooks can append tracking milestones without human input.
Draft creation (log.shipment.create) — write, reversible. An agent can create a draft shipment from a confirmed sales order; a human confirms and dispatches it.

log.shipment.dispatch, log.shipment.deliver, and log.delivery_note.sign carry agentHint: "Human-only" — they require physical confirmation and are excluded from the agent surface.

Enterprise note — Lane-based dispatch routing, multi-tenant carrier cost benchmarking, SLA watchdog automation that auto-escalates exceptions at threshold breach, and Observability Pro per-shipment trace spans are commercial-only capabilities. The open-core runtime, state machine, and permission model described above are available in every edition.

How to get it

Community: build it yourself using the plugin manifest format and command pipeline — both are open-source.
Standard: use the base platform; configure your own logistics-shaped models and commands on top.
Professional: get the logistics solution package — pre-wired models, commands, menus, roles, and dashboards.
Enterprise: same package plus dedicated delivery engineering, carrier integration design, and SLA-backed support.

See Pricing for the full edition comparison.

Next steps

Command pipeline — the execution contract used by every command above
Permissions — the five-layer model used by the Dispatch Agent role
Plugin manifest — how a solution package declares its plugin dependencies
Agent readiness — designing agentHint and risk fields for safe execution
System overview — how plugins, commands, and the runtime fit together