Route Updates

SALLY continuously monitors active routes and updates them when conditions change. This page explains the trigger system, the re-plan vs ETA-update decision, and how route versioning works.

Endpoint

POST /api/v1/routes/update

Authentication: Bearer token required. Roles: DISPATCHER, ADMIN, OWNER.

Request

{
  "plan_id": "RPL-2026021101",
  "trigger": {
    "type": "dock_time_changed",
    "details": {
      "stop_id": "LOC-001",
      "original_dock_hours": 2.0,
      "actual_dock_hours": 4.5,
      "reason": "Loading delays due to staffing shortage"
    }
  },
  "driver_current_state": {
    "latitude": 34.0522,
    "longitude": -118.2437,
    "hours_driven": 3.5,
    "on_duty_hours": 6.0
  }
}

Response

{
  "plan_id": "RPL-2026021101",
  "version": 2,
  "previous_version": 1,
  "update_type": "re_plan",
  "trigger_summary": "Dock time at ABC Distribution Center changed from 2.0h to 4.5h (+2.5h)",
  "impact": {
    "eta_change_hours": 2.5,
    "hos_impact": "Duty window reduced by 2.5h. Rest stop moved earlier.",
    "stops_affected": ["LOC-002"],
    "re_plan_required": true,
    "reason": "HOS impact exceeds threshold. Remaining route requires re-planning."
  },
  "segments": [
    {
      "sequence": 1,
      "type": "drive",
      "from": "Current Location",
      "to": "Truck Stop - I-5 Exit 200",
      "distance_miles": 30,
      "duration_hours": 0.5
    },
    {
      "sequence": 2,
      "type": "rest",
      "location": "Truck Stop - I-5 Exit 200",
      "rest_type": "full_rest",
      "duration_hours": 10.0,
      "reason": "Extended dock time consumed duty window. Full rest required before continuing."
    },
    {
      "sequence": 3,
      "type": "drive",
      "from": "Truck Stop - I-5 Exit 200",
      "to": "XYZ Warehouse",
      "distance_miles": 200,
      "duration_hours": 3.5
    }
  ],
  "compliance": {
    "hos_violations": 0,
    "missed_appointments": 0,
    "overall_status": "COMPLIANT"
  },
  "updated_at": "2026-02-11T14:30:00Z"
}

Trigger Types

SALLY monitors 20 alert types across 6 categories. Each trigger is evaluated to determine whether a re-plan or ETA update is needed.

HOS Triggers

Trigger	Description	Typical Response
`hos_approaching_limit`	Driver within 1h of drive/duty limit	Monitor; ensure rest stop upcoming
`hos_violation`	Active HOS violation detected	Mandatory rest, re-plan route
`break_required`	8h since last break	Insert 30-min break
`cycle_limit_approaching`	Within 5h of 70h cycle limit	Plan extended rest or 34h restart

Route Progress Triggers

Trigger	Description	Typical Response
`dock_time_changed`	Actual dock time differs from estimate	Re-plan if impact exceeds 30 min
`missed_appointment`	Driver missed time window	Contact customer, re-plan
`route_delay`	ETA delay exceeds 30 minutes	Update ETAs, notify customer
`driver_not_moving`	No movement for 2+ hours during drive segment	Alert dispatcher

Load Triggers

Trigger	Description	Typical Response
`load_added`	New stop added mid-route	Re-sequence remaining stops
`load_cancelled`	Stop removed from route	Re-plan with remaining stops

Driver Triggers

Trigger	Description	Typical Response
`driver_rest_request`	Driver wants to rest at current location	Update HOS, re-plan remaining route
`driver_status_change`	Driver changed duty status	Update HOS tracking

External Triggers

Trigger	Description	Typical Response
`traffic_delay`	Real-time traffic alert on route	Re-plan if delay exceeds 30 min
`weather_alert`	Severe weather on route	Adjust speed estimates, re-plan if needed

Re-Plan vs ETA Update

When a trigger is detected, the update handler decides what to do:

Trigger Detected
       ↓
Calculate Impact:
  - HOS hours consumed/changed
  - Time added/removed
  - Stops affected
       ↓
Impact > Threshold?
  ├── YES → Full Re-Plan (invoke Route Planning Engine)
  └── NO  → ETA Update Only (adjust timing, no route changes)

Decision Thresholds

Condition	Decision
ETA change under 30 minutes	ETA update only
ETA change 30+ minutes	Re-plan
HOS violation imminent	Re-plan (always)
Stop added or cancelled	Re-plan (always)
Driver rest request	Re-plan (always)
Traffic delay under 30 min	ETA update only
Traffic delay 30+ min	Re-plan

Update Types

Type	Description
`re_plan`	Full route re-planning. Generates new segment sequence from current location. May re-order stops, insert/remove rest stops.
`eta_update`	Timing adjustment only. Same segments, updated arrival/departure times.
`notify_only`	Informational trigger. No route or timing changes (e.g., route completed).

Route Versioning

Every update creates a new version of the route plan. This provides a complete audit trail.

Field	Description
`version`	Current plan version (increments with each update)
`previous_version`	Version before this update
`trigger_summary`	Human-readable description of what changed
`impact`	Analysis of the trigger’s effect on the route

Example version history:

Version	Trigger	Update Type	Key Change
v1	Initial plan	—	Original route with 8 segments
v2	Dock time extended (+2.5h)	Re-plan	Rest stop moved earlier, 1 segment added
v3	Traffic delay (45 min)	Re-plan	Alternative route segment, ETA +30 min
v4	Driver rest request	Re-plan	Rest inserted at current location

Monitoring Loop

The Continuous Monitoring Service runs in the background, checking every active route every 60 seconds:

For each active route:
  1. Check HOS state (approaching limits?)
  2. Check route progress (on track? delays?)
  3. Check external conditions (traffic? weather?)
  4. Check driver status (moving? resting?)
       ↓
  If trigger detected:
    → Evaluate severity
    → Generate alert (for dispatcher)
    → Determine update type (re-plan / ETA / notify)
    → Execute update
    → Notify driver of changes

Driver Notifications

When a route is updated, the driver receives a notification:

Re-plan: “Route updated. Review changes.” with a diff of what changed
ETA update: “ETA updated. New arrival at Stop B: 3:45 PM (was 3:15 PM)”
Mandatory rest: “Rest required. Navigate to [location] for 10h rest.”

The driver can:

Accept the new route (becomes active)
View changes (see before/after comparison)
Request modification (dispatcher notified)

Error Handling

404 — Plan Not Found

{
  "statusCode": 404,
  "message": "Route plan RPL-INVALID not found",
  "error": "Not Found"
}

409 — Plan Not Active

{
  "statusCode": 409,
  "message": "Route plan RPL-2026021101 is not active (status: completed). Only active plans can be updated.",
  "error": "Conflict"
}

422 — Route Infeasible After Update

{
  "statusCode": 422,
  "message": "Route is not feasible after update: all remaining appointments are past their latest time window.",
  "error": "Unprocessable Entity"
}