Transport OS Guide

Chapter 1 — What Transport OS Gives You

Transport OS turns Trenvar into a TMS — a transport management system. Dispatch jobs to drivers, plan routes, capture POD, and price transport work.

What it adds

Default landing path

/console/business/dispatch/jobs for company_admin focused on transport.

Chapter 2 — Roles That Light Up with Transport OS

Chapter 3 — Setting Up Your Fleet

Before you can dispatch anything, Trenvar needs to know your drivers and your vehicles. This chapter walks through both.

Walkthrough A — invite a driver

Prerequisites

• company_admin or operations_manager.
• Driver's email + name + license info.

Step-by-step

1. Go to /console/business/settings/users. Header: "Users".
2. Click Add User. Modal opens.
3. Fill:
   • Email → driver's email.
   • Display Name → "Mike Johnson".
   • Role → tick driver.
4. Click Save & Send Invite. Trenvar sends Mike an email.
5. Mike accepts, sets a password, signs in. Lands at /console/driver/jobs (empty for now).
6. Now go to /console/ops-manager/drivers. Mike appears in the list.
7. Click on Mike. Detail panel opens. Click Edit Driver Profile.
8. Add driver-specific fields:
   • Driver License Number → text.
   • License Class → dropdown (CDL-A, CDL-B, regular, etc.).
   • License Expiry → date picker.
   • Hours-of-Service Config → optional. Sets daily/weekly drive-time limits visible to dispatch.
   • Default Vehicle → typeahead (must add vehicles first — Walkthrough B).
   • Phone → for dispatch comms.
   • Emergency Contact → name + phone.
9. Save.

Walkthrough B — add a vehicle

Step-by-step

1. Go to /console/ops-manager/fleet. Header: "Fleet". Top-right: Add Vehicle.
2. Click Add Vehicle. Modal opens.
3. Fill:
   • Registration Plate → "ABC-1234". Unique within tenant.
   • Vehicle Type → dropdown: van / box truck / semi / cargo van / sprinter / cube.
   • Make / Model / Year → optional.
   • VIN → optional.
   • Max Payload Weight (kg) → e.g., 4500 for a box truck.
   • Max Payload Volume (m³) → e.g., 22.
   • Insurance Provider → text.
   • Insurance Expiry → date.
   • Inspection Expiry → date.
   • Status → active / out-of-service.
4. Click Add Vehicle. Toast: "Vehicle ABC-1234 added."

Chapter 4 — Dispatch Jobs

A dispatch job is the execution unit for delivering one shipment. Status flow: open → assigned → in_progress → completed, with cancelled at any point.

Walkthrough — create a dispatch job

Prerequisites

• company_admin or operations_manager with dispatch.jobs.create.
• The shipment exists in /console/business/wms/shipments (Warehouse OS) or as a standalone delivery (Transport-only mode).

What the screen looks like

Go to /console/business/dispatch/jobs. Header: "Dispatch Jobs". Filter pills: All / Open / Assigned / In Progress / Completed / Cancelled. Top-right: Create Job.

Step-by-step

1. Click Create Job. Modal opens.
2. Fill:
   • Job Code → leave blank for auto (e.g., DJ-20260503-001) or type your own.
   • Shipment → typeahead. Pick the outbound shipment to deliver.
   • Customer → auto-fills from shipment. Read-only.
   • Transport Mode → dropdown: trucking / rail / ocean / air / parcel. Optional but useful for filtering.
   • Priority → dropdown: normal / high / urgent.
   • Service Window → optional. Date+time-from / date+time-to. The carrier or driver must deliver within this window.
   • Special Instructions → free text. ("Lift gate required. Call from front entrance.")
3. Click Create Job. Job appears in the queue with status open.

Walkthrough — cancel a job

1. Open the job detail.
2. Three-dot menu → Cancel Job.
3. Modal: enter cancellation reason (mandatory dropdown + optional notes).
4. Click Confirm Cancel.
5. Status flips to cancelled. Audit log records actor + reason.

Chapter 5 — Route Planning

A route plan groups several jobs into one ordered sequence assigned to a driver + vehicle. Useful when one driver does multiple stops in a day.

Walkthrough A — build a route plan

Step-by-step

1. Go to /console/business/dispatch/tracking. Two tabs: Route Plans (default) and Live Tracking.
2. Click Create Route Plan (top-right).
3. Modal opens with three sections: Header, Stops, Capacity.
4. Header:
   • Plan Name → "Mike's North Route — May 3".
   • Driver → typeahead. Pick "Mike Johnson".
   • Vehicle → typeahead. Pick "ABC-1234".
   • Date → today.
   • Departure Time → time picker.
5. Stops:
   • Click Add Stop. Search by job code or shipment ref. Pick.
   • Stop is added at the bottom of the list with auto-numbered sequence.
   • Add more stops; drag to reorder, or click the up/down arrows.
6. Capacity (optional):
   • Max Weight (kg) → e.g., 4500. Defaults to vehicle's max payload weight.
   • Max Volume (m³) → defaults to vehicle's max payload volume.
   • Trenvar shows running total: "Current load: 2,840 kg / 4,500 kg (63%), 11.2 m³ / 22 m³ (51%)."
7. Click Create Route Plan. Plan saved with optimization_version = 1.

Walkthrough B — optimize the route

1. Open the route plan detail.
2. Click Optimize (top-right).
3. Modal: pick optimization criterion — shortest distance / shortest time / tightest service windows.
4. Click Run Optimization. Spinner.
5. Result: re-sequenced stops shown side-by-side with the old order. Estimated savings shown ("Saved 32 km, 47 minutes").
6. Click Apply to commit. Plan now has optimization_version = 2; old version preserved in history.
7. Click Discard to keep the original sequence.

Chapter 6 — Driver Assignment & Live Tracking

Walkthrough A — assign a driver to a single job (without a route plan)

1. Open the job from /console/business/dispatch/jobs.
2. The detail panel shows the job in open status with no assigned driver.
3. Click Assign Driver.
4. Modal: typeahead from active drivers. Pick "Mike Johnson".
5. Optionally pick a vehicle.
6. Click Assign. Job status flips to assigned.
7. Mike sees the job in /console/driver/jobs within seconds.

Walkthrough B — monitor live tracking

1. Go to /console/business/dispatch/tracking → Live Tracking tab.
2. Map view loads. Each active driver shows as a pin with their initials and a colored badge: green (active, recent ping), yellow (stale, 1–3 min), red (offline, >3 min).
3. Click a pin → side panel shows: driver name, current job, route plan, last ping time, speed, estimated time-to-next-stop.
4. Filter the map by route plan, driver, or status.

How tracking works under the hood

Drivers publish GPS via POST /api/dispatch/driver-location. The server enforces "you can only publish your own location" — so a driver can't spoof another's. Operations managers read all locations via GET /api/dispatch/driver-location/active. Drivers go stale after 3 minutes of no ping.

Chapter 7 — Walkthrough: A Driver's Day

End-to-end walkthrough from a driver's perspective. Mike Johnson clocks in at 8 AM, runs his route, finishes at 5 PM.

Step-by-step

1. Mike opens his phone's browser. Goes to www.trenvar.com/acme-warehouse/login.
2. Signs in. Lands at /console/driver/jobs. Sees today's 8 jobs as cards, ordered by route sequence.
3. Each card: stop number, customer, address, time window, special instructions. Status pill says assigned.
4. Mike clicks the first card. Detail screen.
5. He clicks Accept & Start. Status moves to in_progress. GPS prompt appears: "Allow location sharing?" → Allow. GPS pings start.
6. Drives to the customer.
7. On arrival, clicks Mark Arrived. The system records the arrival timestamp.
8. Captures POD (Chapter 8).
9. Clicks Complete. Status flips to completed. Card disappears from active list (visible in History).
10. Mike taps the next card in his sequence and repeats.
11. End of day: all jobs completed. Mike clicks his initials → Sign out. GPS pings stop.

What dispatch sees while Mike is working

• Live map at /console/business/dispatch/tracking shows Mike's pin moving in real-time.
• Each completed POD shows up immediately in the dispatch console.
• If Mike falls behind schedule, dispatch can intervene: call him, reassign a stop to another driver, or ping the customer.

Chapter 8 — Proof of Delivery (POD)

A POD is the legal record of delivery. Driver captures it in the field; once finalized it's immutable. This chapter walks through capture from the driver's side and what dispatch sees in real-time.

Walkthrough — driver captures a POD on a phone

Prerequisites

• driver role with dispatch.pod.create.
• Job in in_progress status.
• Phone has camera + touch screen for signature.
• Browser permissions: location + camera.

Step-by-step

1. Driver Mike has marked Arrived at the customer. He taps the job's Capture POD button.
2. POD form opens with these fields:
   • Delivery Outcome → radio: Delivered / Partial / Failed.
   • Recipient Name → text. ("John Doe").
   • Recipient Title → optional. ("Receiving Manager").
   • Notes → optional. ("Left with reception, called recipient on cell.")
3. Mike fills outcome = Delivered, recipient name = John Doe.
4. Tap Capture Signature. Full-screen signature pad opens. Recipient signs with their finger or stylus. Tap Done. Signature saved as PNG.
5. Tap Take Photo. Camera opens. Mike snaps:
   • The package at the door / on the dock.
   • The signed paperwork.
   • Any visible damage (if applicable).
6. Each photo appears as a thumbnail. Tap a thumbnail to delete or retake.
7. Once outcome + recipient name + signature OR photo is captured, the Finalize POD button activates.
8. Tap Finalize POD. Confirmation: "Finalize POD for J-2026-001? This cannot be edited later."
9. Confirm. Trenvar uploads the photos + signature, writes the POD record, marks the job as ready to complete.
10. Mike returns to the job and clicks Complete. Job → completed.

Worked example — partial delivery

Mike delivers 8 of 10 boxes (2 are damaged at warehouse and held back).

1. Outcome = Partial.
2. Recipient name = John Doe.
3. Notes = "8 of 10 boxes delivered. Boxes 9 + 10 held at warehouse for repackaging — see ticket #1042."
4. Signature captured on the partial-delivery acceptance form.
5. Photos: 8 boxes at the door, the partial-delivery form.
6. Finalize.

What dispatch sees

The moment Mike finalizes, the POD shows in real-time on:

• /console/ops-manager/pod — POD list with status, customer, outcome, photos.
• The original job's detail page — POD link with photo thumbnails.
• Customer service can pull it up if the customer disputes.
• The customer's portal (if Transport-aware) — they see "Delivered" with photo thumbnail and signature.

Chapter 9 — POD Corrections

PODs are immutable once finalized. To fix mistakes, ops managers create a correction record — never an edit.

Walkthrough — correct a finalized POD

Prerequisites

• operations_manager (or company_admin) with dispatch.pod.correct.
• The POD is finalized.
• You have a clear reason for the correction.

Step-by-step

1. Go to /console/ops-manager/pod.
2. Find the POD you need to correct (filter by job code, customer, date).
3. Click the row. Detail panel opens with the original POD: outcome, recipient name, photos, signature, notes.
4. Click Correct POD (top-right).
5. Modal:
   • Correction Reason → mandatory dropdown: Recipient name misspelled / Wrong outcome / Photo replaced / Signature retaken / Other.
   • Correction Notes → optional free text.
   • Patch Fields → tick which fields to override:
     • Recipient Name → new value.
     • Delivery Outcome → new value.
     • Photo Refs → upload replacements.
     • Signature → re-capture.
6. Click Submit Correction.
7. Trenvar writes a new podCorrection record linked to the original POD. The original is unchanged.
8. The "effective POD" displayed everywhere is the original merged with the latest correction patch.
9. Audit trail shows: original POD by Mike at 14:32, correction by Sarah at 16:05 with reason and patch.

Worked example

POD captured with recipient = "Jonh Doe" (typo). Customer service notices when reviewing. Sarah (operations_manager):

1. Opens the POD, clicks Correct POD.
2. Reason = Recipient name misspelled. Patch = Recipient Name → "John Doe".
3. Submits. The POD now displays "John Doe" everywhere; the audit shows the original misspelling + the correction.

Chapter 10 — Transport Pricing

Transport pricing is its own family of rules — distinct from warehouse fulfillment pricing. Set up base rates, accessorials, fuel, and customer-specific contracts.

Source types under Transport OS

Walkthrough A — create a base distance rate

Step-by-step

1. Go to /console/business/billing/pricing-rules.
2. Click Create Rule.
3. Source Type → "Transport: Rate".
4. Rule Name → "Standard Distance Rate".
5. Customer → leave blank for tenant-wide default.
6. Base Rate Style → distance.
7. Distance Unit → km or mi.
8. Distance Rate → 0.75 ($0.75 per km).
9. Minimum Charge → 30 ($30 floor regardless of how short the trip).
10. Vehicle Types → optional. Tag input for which vehicle types this rule applies to.
11. Save.

Walkthrough B — create a flat lane rate

1. Same screen. Click Create Rule.
2. Source Type = "Transport: Rate". Style = lane.
3. Origin Zone → "VAN" (define zones in shipping settings).
4. Destination Zone → "CAL".
5. Lane Key → optional shorthand "VAN-CAL".
6. Flat Amount → 325.
7. Save. Trenvar will use this rule for every job from VAN zone to CAL zone.

Walkthrough C — create an accessorial rule

1. Click Create Rule.
2. Source Type = "Transport: Accessorial".
3. Rule Name = "Liftgate Service".
4. Charge Type → per_use / per_hour / flat.
5. Amount → 35 (per use).
6. Default Quantity → 1 (auto-applied if applicable).
7. Save. When a dispatch job is flagged "Liftgate required", this charge is added.

Walkthrough D — create a fuel surcharge

1. Source Type = "Transport: Fuel".
2. Fuel Mode → flat_percent (single % of base) or distance_brackets (varies by trip length).
3. If flat: Percent Flat → 12 (12%).
4. If brackets: add rows like "0–100km = 8%", "100–500km = 12%", "500+km = 15%".
5. Save. Applied automatically on every transport invoice line.

Walkthrough E — customer contract (override rates for one customer)

1. Source Type = "Transport: Contract".
2. Customer → "Acme Corp".
3. Pick which base rules to override:
   • Rate Card Code → reference your default. Or override entirely.
   • Discount Percent → 8 (8% off everything).
   • Base Rate Multiplier → 0.92 (alternative way to say "92% of base").
   • Lane Overrides → table of specific lane prices that override the default.
   • Accessorial Overrides → e.g., "Liftgate free for Acme".
4. Save. For Acme's jobs, this contract supersedes the default rules.

Worked example — calculating a transport invoice line

Acme job: 340 km from Vancouver to Calgary, 2 stops, liftgate required.

• Base rate (lane): VAN-CAL flat = $325.
• Acme contract discount: -8% = $325 × 0.92 = $299.
• Stop charge: 2 stops included free, 0 extras = $0.
• Liftgate: free under Acme contract = $0.
• Fuel surcharge: 12% of $299 = $35.88.
• Total transport line: $334.88.

Chapter 11 — Daily Flow per Role

Operations manager's day

1. Open dispatch board.
2. Triage open jobs; assign drivers based on availability.
3. Build and optimize route plans.
4. Watch live tracking; intervene on stalled drivers.
5. Finalize POD corrections submitted by customer service.

Driver's day

1. Log in to /console/driver/jobs.
2. Accept jobs in order.
3. Drive, mark arrived, capture POD, complete.
4. End of day: review tomorrow's preview.

Customer service's day

1. Read tracking for customer questions ("where's my shipment?").
2. Open POD history for delivery confirmations.
3. Open cases for delivery disputes.

Appendix A — Transport OS Console Paths

Appendix B — Transport OS Permissions

Appendix C — Glossary

Every Transport-OS-specific term, in plain English.

Accessorial — An add-on transport charge: liftgate, extra stops, detention, wait time, redelivery.

Capacity envelope — A vehicle's maximum payload weight + volume. Trenvar enforces it on route plans.

Carrier — The company actually moving the freight (FedEx, UPS, DHL, USPS, your own fleet).

Customer contract — A transport pricing rule scoped to one customer that overrides default rate, accessorial, or fuel rules.

Dispatch board — The screen showing all active dispatch jobs and route plans; central console for ops managers.

Dispatch job — The unit of work for delivering one shipment. Lifecycle: open → assigned → in_progress → completed (or cancelled).

Driver — A tenant user with the driver role. Sees only their own assigned jobs.

Fleet — Your collection of vehicles + drivers.

Fuel surcharge — A pricing rule that adds a percentage (or distance-bracketed) charge on top of the base rate.

Lane — A specific origin → destination pair (e.g., VAN → CAL). Lane rates set a fixed price for that route regardless of distance.

Live Tracking — Real-time map view of active drivers' GPS locations. Drivers go stale after ~3 minutes of no ping.

POD (Proof of Delivery) — The legal record of delivery: photo, signature, recipient name, outcome. Captured by the driver; immutable once finalized.

POD Correction — How an ops manager fixes a mistake on a finalized POD. Original POD is immutable; the correction is a separate audit-logged record that overrides specific fields.

Rate card — Your set of base transport rates (flat, distance, lane).

Route plan — An ordered sequence of stops assigned to a driver + vehicle. Has an optimization version that bumps when re-sequenced.

Stop — One delivery point on a route plan. Most plans have multiple stops.

Stop charge — Per-stop pricing rule. Typically N stops included free, plus extra-per-stop after.

Transport mode — How freight moves: trucking, rail, ocean, air, parcel.

Vehicle — A truck, van, or other unit in your fleet. Has plate, type, max payload, expiry dates.

Write-mode impersonation — Platform-admin capability to make changes inside a tenant while signed in as a tenant user. Audit-loud and dangerous.

End of Transport OS Guide  ·  v1.0  ·  May 2026