Skip to main content

Trucking Dispatch & Scheduler – Current Implementation

1. Overview​

  • Feature name: Trucking Dispatch & Scheduler
  • Primary users: Dispatchers, operations managers, drivers (indirectly)
  • Industries: Trucking (with shared infrastructure for service/repair)
  • What this feature solves today:
    • Provides a visual scheduler for assigning trucking loads/legs to drivers/resources over time.
    • Calculates time ranges (start/end) for trucking legs using configurable travel-time and HOS rules.
    • Feeds assigned legs to the mobile app so drivers can see their daily work.

2. Repos & Entry Points​

API (@attunelogic-api)​

  • Docs
    • docs/api/schedule.md – Time range calculation and Schedule API overview.
  • Types & Config
    • src/types/index.ts – TruckingJob, TruckingLeg (used in schedule responses).
    • src/services/config/default-configs/job.js and schedule-related config entries.
  • Controllers / Services
    • Schedule logic lives in the scheduling service/module (referenced by schedule routes).
  • Routes
    • GET /api/v1/schedule – Returns scheduled events and resources.
    • GET /api/v1/schedule/unassigned – Returns unassigned jobs/legs and available resources.

Web (@attunelogic-service)​

  • Scheduler component
    • src/shared/Scheduler/*:
      • Scheduler/index.tsx – Main entry for the scheduler UI.
      • SchedulerGrid.tsx – Core grid with drag-and-drop behavior and view switching.
      • SchedulerToolbar.tsx – Date navigation, view selection, zoom.
      • Views/Timeline, Views/Day, Views/Week, Views/Month, Views/List, Views/Map.
    • Documented in attunelogic-service/docs/SCHEDULER_COMPONENT.md.
  • Dispatch/Jobs integration
    • Scheduler is used in dispatch views to:
      • Visualize trucking legs and jobs as timeline events.
      • Assign legs to drivers/resources by drag-and-drop.
    • Jobs and legs come from the Jobs/Loads & Legs system described separately.

Mobile (@attunelogic-mobile)​

  • Tabs + navigation
    • app/(app)/(tabs)/_layout.tsx – schedule tab titled “Loads” when appType === "trucking".
  • Schedule & driver view
    • app/(app)/(tabs)/schedule/index.tsx – Schedule tab implementation.
    • features/Job/DriverLoads.tsx – Calendar + list view of legs per driver per day.
    • features/Load/LoadShow.tsx – Shows load/leg details when a driver taps an item.
  • Data access
    • store/api/legs/api.ts – useGetLegsQuery and useGetLegByIdQuery.
    • store/api/jobs/api.ts – useGetJobsQuery for job-level schedule views when needed.

3. Current Implementation (By Platform)​

3.1 Backend API​

Time range calculation (trucking)​

From docs/api/schedule.md:

  • For trucking, the scheduler calculates realistic time windows using:
    • Distance-based travel time:
      • Distance from route mileage.
      • Average speed (default: 55 mph).
    • Buffers & inspections:
      • Buffer time (default: 30 minutes).
      • Pre-trip inspection (default: 15 minutes).
      • Post-trip inspection (default: 10 minutes).
    • Legal breaks (HOS-aware):
      • 30-minute break after 8 hours of driving.
      • Additional breaks for each additional 8-hour block.
  • The appointment date/time on the leg is treated as the arrival/delivery time; the scheduler works backwards to compute a realistic start time.

Schedule endpoints​

  • GET /api/v1/schedule:
    • Returns:
      • events: job/leg events with timeRange.start/end, route info, and metadata.
      • resources: drivers/technicians or other resources with status.
  • GET /api/v1/schedule/unassigned:
    • Returns unassigned jobs/legs and resources to support the “unassigned queue” in the scheduler UI.

Multi-tenant & industry behavior​

  • Schedule queries and calculations respect:
    • parentCompany scoping.
    • appType (trucking vs serviceRepair) to determine:
      • Speed assumptions.
      • Use of HOS and inspection times.
      • Default durations for service jobs vs trucking legs.

3.2 Web App (Service)​

Scheduler UI​

From docs/SCHEDULER_COMPONENT.md:

  • The Scheduler is a shared, configurable component that supports:
    • Multiple views (Timeline, Day, Week, Month, List, Map).
    • Drag-and-drop of events in the Timeline view with 30-minute snapping:
      • During drag: movement is snapped visually to 30-minute intervals.
      • On drop: final start time is snapped to the nearest 30-minute block.
    • Resource rows representing drivers/vehicles or other assets.
    • A toolbar for date navigation, view switching, and zoom control.

Trucking-specific usage​

  • In trucking contexts (appType === "trucking"):
    • Events largely represent legs (or load segments) associated with Job and Leg data from the API.
    • Resources are typically drivers (and may include vehicles in future phases).
  • The scheduler supports:
    • Assigning legs to drivers by vertical drag-and-drop.
    • Adjusting timing by horizontal drag within legal time windows.
    • Viewing unassigned loads/legs in a separate list (unassigned queue) and dragging them into the grid.

Current entry point & usage​

  • In real usage today:
    • Dispatchers typically begin on the Job/Load detail page, then open scheduling/dispatch views as needed.
    • A dedicated “dispatcher cockpit” workflow is still emerging; the scheduler is powerful but used more as an advanced tool than a single, always-on control center.
  • Production usage for trucking is currently light / early-phase:
    • One trucking customer uses related job/leg flows in a bare-bones way.
    • The long-term goal is a dispatcher-focused, all-in-one system, but that is not yet fully realized.

Integration with job/leg data​

  • Jobs and legs (created via the Job & Leg Creation system) are transformed into scheduler events:
    • Event fields:
      • id – underlying job/leg ID.
      • title – often Load #<loadNumber> or a customer/route summary.
      • timeRange.start/end – based on API schedule calculations.
      • assignedResources – driver/resource IDs.
  • When an event is dropped in a new time/resource slot:
    • The scheduler calls onEventDrop / onEventChange handlers.
    • The app updates the underlying job/leg via API (e.g., setting driverId, appointmentDate, or time fields).

3.3 Mobile App​

Driver-centric schedule view​

  • For appType === "trucking":
    • The schedule tab shows “Loads” and focuses on driver legs, not the full dispatch board.
    • DriverLoads.tsx:
      • Fetches legs for the current driver and selected date range.
      • Uses a calendar to pick dates and a list of LegCard components to show each leg.
  • Mobile does not render the full scheduler grid; instead, it presents:
    • A per-driver, per-day view of assigned legs.
    • A drill-down to LoadShow / LoadDetails for more information and actions.

Connection to web scheduler​

  • Assignments made on the web scheduler (driver + time) affect which legs:
    • Appear in the driver’s mobile schedule.
    • Are visible on which dates.
  • Today this connection is primarily via:
    • Leg assignments (driverId) and appointment/time fields stored in the API.
    • Querying legs filtered by driverId and date range on mobile.

4. Status & Completeness​

Implemented today​

  • API:
    • Schedule endpoints to retrieve events/resources and unassigned work.
    • Configurable time range calculations for trucking vs service/repair.
    • Integration with Jobs/Legs models to build trucking events.
  • Web:
    • A reusable scheduler UI component with multi-view support and drag-and-drop.
    • Trucking-friendly Timeline view with 30-minute snapping and resource rows.
    • Integration with Jobs/Legs to assign work to drivers from an unassigned queue.
  • Mobile:
    • Driver-focused leg listing per day with basic schedule navigation.
    • Load/leg detail screens accessible from the schedule tab.

Partial / early implementations​

  • HOS-based constraints are modeled in config and schedule docs but are not yet fully surfaced in the UI (e.g., no hard enforcement overlays or warnings in the scheduler itself).
  • Web scheduler is powerful but still tuned more for internal ops; driver-centric schedule features (reminders, better conflict handling) are minimal.
  • Mobile shows legs per day but does not yet visualize durations, conflicts, or HOS constraints; it’s closer to a list than a calendar timeline.

Missing / not implemented​

  • Real-time dispatch updates (e.g., WebSockets) wired all the way through scheduler and mobile for instant changes.
  • Advanced trucking routing and optimization (traffic-aware ETAs, VRP, truck-specific routing) are planned but not yet implemented.
  • Full HOS integration into the scheduler’s drag-and-drop logic (e.g., preventing illegal assignments at the UI level).

5. Dependencies & Configuration​

  • Customer config (useCustomerConfig):
    • Provides schedule-related configuration:
      • Default durations.
      • Travel speed assumptions for trucking vs service.
      • HOS / legal breaks toggles and thresholds.
  • Industry / appType:
    • appType === "trucking":
      • Uses trucking travel speeds and HOS rules.
      • Scheduler events represent legs; mobile schedule tab is labeled “Loads”.
    • appType === "serviceRepair":
      • Uses different defaults and focuses on service appointments instead of legs.
  • Roles / permissions:
    • Dispatcher/manager roles access the full scheduler and can modify assignments.
    • Drivers interact with their own schedule and loads only.

6. UX Notes & Known Issues​

  • What users experience today:
    • Dispatchers:
      • Can visually assign legs to drivers, adjust times, and see unassigned work.
      • Experience a modern drag-and-drop scheduler with multiple views.
    • Drivers:
      • See their assigned legs as a date-based list and can drill into details.
  • Known rough edges:
    • The scheduler configuration is powerful but complex; behavior can vary subtly by tenant/industry.
    • HOS and routing constraints are informative rather than strictly enforced in the UI.
    • Mobile schedule view is not yet as trucking-specific and driver-centric as the long-term roadmap describes.

7. Roadmap Alignment​

  • Relevant roadmap sections:
    • API docs/MASTER_ROADMAP.md – Enhanced routing & scheduling system, trucking scheduling phases.
    • Service docs/MASTER_ROADMAP.md – Scheduler/dispatch enhancements and universal dispatch goals.
    • Mobile docs/MASTER_ROADMAP.md – Trucking schedule improvements and route management features.
  • What’s planned vs what exists:
    • Planned:
      • Real-time traffic integration, advanced routing, multi-stop optimization.
      • HOS-aware scheduling with clear warnings/enforcement.
      • Full universal dispatch system covering all industries with standardized UI.
    • Exists:
      • Solid foundation with a flexible scheduler UI tied to Jobs/Legs and basic driver schedule views on mobile.

8. Testing & Risk​

  • Tests:
    • API:
      • Schedule calculation logic covered indirectly via job/schedule tests.
      • Configuration-driven behavior validated in unit tests (where present).
    • Service:
      • Scheduler component tests (drag-and-drop, snapping) and some integration tests.
    • Mobile:
      • Minimal automated tests for schedule; behavior verified primarily through manual QA.
  • Risks / edge cases:
    • Mismatched configuration across tenants leading to surprising time ranges.
    • Assignments that technically violate HOS rules but are not clearly flagged in the UI.
    • Race conditions between dispatch changes and mobile sync if real-time updates are not fully wired.
  • Monitoring:
    • Operational issues tend to appear as:
      • Support tickets about incorrect times/assignments.
      • Driver feedback about loads not appearing where expected.
      • Performance or error logs around schedule endpoints and scheduler-heavy pages.

9. Current Adoption & Next Steps​

  • Current adoption:
    • The scheduler is production-ready but currently used in a light / early-phase way for trucking.
    • FC Trucking and Logistics Inc. uses job/leg flows in a bare-bones pattern; most day-to-day operations still start from the Job page rather than a dedicated dispatcher cockpit.
  • Next steps:
    • Design and implement a clearer dispatcher role and cockpit that centers around the scheduler and unassigned queue.
    • Surface more HOS and routing constraints visually in the scheduler (warnings/indicators) even before full enforcement logic.
    • Tighten the loop between web scheduler changes and mobile driver views (consider real-time updates and better conflict feedback).