Skip to main content

Trucking Dispatch Alerts – Developer Guide

Purpose​

This document explains how trucking dispatch alerts are produced, transported through the schedule payload, and rendered in the dispatch modal.

The current design separates:

  • Actionable/review alerts that should drive dispatcher workflow
  • Data-quality/info alerts that should be visible without looking like operational failures
  • Workflow state that persists on the Leg document and controls review UX

High-level flow​

flowchart LR
  legData[LegAndRouteData] --> timingCalc[TruckingEventTimeService]
  timingCalc --> schedulerEvent[ScheduleEventTimeRange]
  schedulerEvent --> dispatchModal[DispatchEventModal]
  dispatchModal --> workflowUpdate[LegAlertWorkflowUpdate]
  workflowUpdate --> refetch[ScheduleRefetch]
  refetch --> dispatchModal

Primary files​

API​

  • @attunelogic-api/src/services/schedule/trucking-event-time.service.js
  • @attunelogic-api/src/controllers/schedule/index.js
  • @attunelogic-api/src/models/Leg.js

Service web app​

  • @attunelogic-service/src/modals/DispatchEventModal.tsx
  • @attunelogic-service/src/shared/Scheduler/types/common.ts

Alert payload contract​

Trucking schedule events keep the legacy warnings array for compatibility, but now also include structured alert metadata in timeRange.alerts.

Example shape:

{
  "timeRange": {
    "start": "2026-04-05T21:30:00.000Z",
    "end": "2026-04-06T20:24:38.000Z",
    "multiDay": true,
    "alerts": [
      {
        "code": "hos_rest_required",
        "type": "action_required",
        "severity": "high",
        "message": "Trip exceeds the FMCSA 11-hour driving window and requires overnight rest planning.",
        "actionable": true
      }
    ],
    "warnings": [
      "Trip exceeds the FMCSA 11-hour driving window and requires overnight rest planning."
    ],
    "requiresAttention": true
  }
}

Alert types​

Recommended/current type meanings:

  • action_required: dispatch should take action
  • needs_review: dispatch should review before release
  • data_quality: timing confidence or route data issue
  • info: useful context without urgency

How requiresAttention works​

requiresAttention should only be derived from actionable/review alerts, not from every warning string.

That means:

  • HOS and workflow-driving alerts should set requiresAttention = true
  • fallback timing or stale cache alerts should stay visible without setting requiresAttention = true

Workflow persistence model​

The workflow state persists on Leg.alertWorkflow.timingAlert.

Current fields:

  • needsReview
  • reviewStatus
  • reviewedAt
  • reviewedBy
  • restPlanStatus
  • planNotes

This keeps workflow persistence separate from the transient alert classification while avoiding a second alert storage model.

Current workflow states​

  • pending
  • reviewed
  • resolved
  • ignored

Important nuance​

reviewed does not always mean “fully complete.”

A leg can be:

  • reviewed and complete
  • reviewed but still waiting on a rest-plan decision

The UI should therefore use both reviewStatus and restPlanStatus / needsReview when deciding whether follow-up is still open.

The dispatch modal currently uses three layers:

1. Compact alert summary​

  • shown near the top of the details tab
  • collapsed by default to reduce noise
  • shows alert count, review status, and rest-plan status

2. Expanded alert detail​

  • shows actionable alert content and informational notes separately
  • only visible when the summary is expanded

3. Workflow panel​

  • drives dispatcher actions such as review, ignore, message driver, or rest-plan follow-up
  • can collapse into a summary state after the main workflow action is taken

Customer-facing visual rules​

  • Amber: follow-up still needed
  • Blue: reviewed and currently complete
  • Gray: ignored / muted

Keep the review state and the rest-plan state visually separate. A leg may be reviewed while still needing rest-plan follow-up.

Current action behavior​

  • Mark Reviewed: marks the alert as reviewed
  • Message Driver: opens communications without changing workflow persistence
  • Add Rest Plan: marks rest-plan follow-up as needed and opens plan notes
  • Ignore: mutes the alert workflow
  • Ignore Rest Plan: clears the rest-plan follow-up while keeping the alert reviewed

Implementation guardrails​

  • Preserve warnings for any older consumers
  • Keep schedule response shape backward compatible
  • Treat structured alerts as additive metadata, not a replacement transport
  • Keep workflow persistence on Leg.alertWorkflow.timingAlert
  • Prefer optimistic UI updates in the modal so colors/status change immediately after action

Operational / workflow:

  • hos_rest_required
  • started_after_appointment
  • appointment_missed
  • multi_day_unplanned
  • rest_plan_missing

Data quality / confidence:

  • route_timing_fallback
  • route_timing_stale_cache
  • missing_route_duration
  • missing_location_data

Testing guidance​

When verifying changes, cover at least:

  • actionable alert produces requiresAttention = true
  • data-quality-only alert produces requiresAttention = false
  • reviewed-complete workflow renders blue
  • reviewed-with-follow-up renders blue review state plus amber follow-up state
  • ignored workflow renders gray
  • collapsed alert summary expands and contracts without hiding required follow-up actions