The Logistics module — exposed at /logistics/delivery/* (staff) and /client/logistics/* (driver/customer) — runs the operational delivery layer for orgs that own their fleet. It manages delivery jobs (pickup → dropoff), an agent (driver) roster with availability and zone assignment, real-time job status, proof of delivery, and per-job pricing and adjustments.
This is a same-day / on-demand delivery surface, not a parcel-carrier integration. If you're shipping with UPS, FedEx, USPS, or DHL through the Storefront, that's handled by the Storefront's shipping rate adapters under /storefront/shipping/*. The Logistics module is for when you own the trucks, riders, or couriers.
Concepts
| Concept | Owns |
|---|---|
| Job | A delivery job. Has stops (pickup + one or more dropoffs), requirements, scheduling, pricing, status |
| Stop | A pickup or dropoff at a specific address with contact info and access notes |
| Agent | A driver / rider. Has profile, vehicle, zone, online status, location, performance stats |
| Zone | A geographic area used for agent assignment and surge pricing |
| Tracking | Live agent location streamed during the job |
| POD | Proof of delivery — photo, signature, timestamp |
| Issue | A reported problem (damaged, missing, refused) with optional escalation |
| Adjustment | A tip, surcharge, refund, or correction applied to a job's price |
Three controllers
| Controller | Path | Principal | What for |
|---|---|---|---|
DeliveryController | /logistics/delivery/* | User (staff) | Zones, agents, jobs, assignment, adjustments, payment, stats |
DeliveryClientController | /client/logistics/* | Customer or driver JWT | Driver app — register, set availability, accept jobs, update status, upload POD; or customer order tracking |
The driver and the buying customer share the same controller — the role is differentiated by the data on the JWT (driver vs customer agent record), which gates which routes apply. Customer routes are clearly labelled (/orders/*, /quote); driver routes carry the agent-specific shape (/jobs/*/start-pickup, /availability, /location).
What's in each page
- Shipments — creating jobs, the pickup → dropoff lifecycle, status transitions.
- Carriers — agent (driver) management, zones, assignment, broadcast.
- Tracking — live status updates, location streaming, customer-side tracking.
- Proof of delivery — photo, signature, timestamps.
- Returns — return jobs, label generation.
Pricing and payment
Each job carries a pricing block with base, distance, surcharges, taxes, and tips. The Logistics module integrates with both Stripe and PayPal directly for customer payment (POST /client/logistics/stripe/intent) and routes driver payouts through the Finance module (POST /client/logistics/payouts/request).
Multi-tenant boundary
Like everything else in AppEngine, jobs and agents are scoped per org. A driver registered in org A cannot see jobs in org B. Geographic data (zones, addresses) is namespaced per org as well — a delivery zone called downtown in two different orgs is two different records.
The module uses the term "agent" for delivery drivers — not to be confused with AI agents in the AI module. It's a historical naming choice we're stuck with.