Skip to main content

Trucking Jobs/Loads & Legs – Current Implementation

1. Overview​

  • Feature name: Trucking Jobs/Loads & Legs
  • Primary users: Dispatchers, back-office ops, drivers (via legs), mobile users
  • Industries: Trucking
  • What this feature solves today:
    • Represents a load as a Job with trucking-specific fields and one or more Legs.
    • Supports both manual entry and file-based import (roughly 50/50 in practice) for multi-stop loads with mileage and rate calculations.
    • Exposes legs to scheduling/dispatch and to the mobile app as driver work items.

2. Repos & Entry Points​

API (@attunelogic-api)​

  • Models
    • src/models/Job.js – Job/load container
    • src/models/Leg.js – Individual trucking legs
  • Types
    • src/types/index.ts – TruckingJob, TruckingJobStatus
    • src/types/models.ts – TruckingJobSchemaFields, TruckingLegSchemaFields
  • Controllers / Services
    • src/controllers/jobs/create.js – Job creation (modern + legacy with legs)
    • src/controllers/jobs/all.js, getById.js – Listing and retrieval
    • src/controllers/legs/create.js (referenced from legacy create)
    • src/controllers/jobs/items.js – Job items / service items (more service-repair focused, but shares job container)
  • Routes
    • src/routes/api/v1/jobs.js
    • src/routes/api/v1/legs.js (if enabled via features/config)

Web (@attunelogic-service)​

  • Job creation & editing
    • src/pages/Jobs/CreateModal/index.jsx – Orchestrates job creation.
    • src/pages/Jobs/CreateModal/TruckingJobForm.tsx – Trucking-specific job + legs form.
    • src/utils/data-generators/index.ts – generateLeg helper (maps form state into ILeg objects).
  • Job display
    • src/pages/Jobs/Show/index.jsx – Job detail view (switches by appType).
    • src/pages/Jobs/Show/Info/Trucking/LegsInfo.jsx – Displays trucking legs within a job.
  • File-based leg creation
    • src/components/FileProcessor/* – File upload and extraction.
    • src/components/FileProcessor/configs.js – createLegsFromData and trucking load extraction presets.
  • Types
    • src/types/index.ts – IJob, ILeg, trucking-related job/leg types.

Mobile (@attunelogic-mobile)​

  • Data types
    • types/index.ts – ILeg, IJobItem = ILeg | IMaintenance.
  • RTK Query slices
    • store/api/jobs/api.ts – Job queries/mutations.
    • store/api/legs/api.ts – Leg queries for driver views.
  • UI components
    • components/LegCard/* – Leg summary cards.
    • components/JobCard/* – Job/load cards (appType-aware).
    • features/Job/DriverLoads.tsx – Calendar + leg list per driver.
    • features/Load/LoadShow.tsx and features/Load/LoadDetails.tsx – Load/leg detail screen(s).

3. Current Implementation (By Platform)​

3.1 Backend API​

Data model​

  • Job (Job model, trucking fields):

    • jobId, client, parentCompany, author, assignedTo[]
    • Trucking-specific fields:
      • drivers: ObjectId[] – associated driver(s)
      • loadNumber: string – load identifier (also used as jobId/orderNumber in create flow)
      • legs: ObjectId[] – references to Leg documents
      • Rates: base, baseRate, fuelRate, flatRate, useFlatRate, useGlobalRates
    • Financial and approval-related fields (shared with service/repair) from mixins.

  • Leg (Leg model, trucking leg):

    • Tenant & parent relationships:
      • parentCompany, jobId, client, author
    • Trucking metadata:
      • status (default "Pending"), active
      • orderNumber, loadNumber, loadType
      • driver (ObjectId → User)
      • appointmentDate, appointment (date, time, number)
    • Route & metrics:
      • route (ObjectId → Route with mileage and location links)
      • weight, waitTime, sortKey
    • Payout fields:
      • payoutType, payoutRate, mileageRate, hourlyRate, etc.

Job creation​

  • Modern createJob (src/controllers/jobs/create.js):

    • Uses useAuth() and useCustomerConfig() to get employeeId, role, appType, and getRates.
    • Generates an orderNumber like CLIENTSLUG-000123 and uses it for:
      • orderNumber, loadNumber, and jobId if not supplied.
    • Populates trucking rate fields based on:
      • Global vs client-specific rates.
      • appType (trucking vs serviceRepair) and useGlobalRates.
    • Creates the Job first; legs are attached via other flows (file extraction or legacy multi-create).

  • Legacy legacyCreate (still present for backward compatibility):

    • Accepts a data.legs map, builds multiple leg payloads, and calls createLeg for each.
    • Aggregates created leg IDs into job.legs and sets drivers array.
    • Applies flat-rate or mileage/fuel/base charges to the job.
    • This is primarily used by older flows and tests; modern UI aims to use createJob + leg creation workflows.

Security & tenancy​

  • All job and leg operations are scoped by:
    • parentCompany (multi-tenant isolation).
    • Auth middleware (verifyToken, verifyParent, verifyRole) on routes.
  • itemsModel and other mixed fields allow the same Job model to support both trucking and service/repair, controlled by customer config.

3.2 Web App (Service)​

Job creation flows​

  • Manual job + leg creation (used frequently in production):

    • CreateModal presents a trucking job creation flow when appType === "trucking".
    • TruckingJobForm.tsx:
      • Collects job-level data (client, base/fuel/flat rates, load number, transaction date, etc.).
      • Manages an internal legsFormState array representing leg drafts.
      • Converts legsFormState → ILeg[] using convertLegsFormStateToILeg and sends to API.
    • Each leg includes:
      • Identification: dropNumber, orderNumber, loadNumber, loadType, weight.
      • Associations: driverId, driver, origin, destination.
      • Route data: route with mileage.
      • Financials: totalMiles, baseCharge, fuelSurcharge, dropCharge, otherCharges, totalCharges.
      • Appointment data: appointmentDate and time-related fields.

  • File-based leg creation:

    • FileProcessor + configs:
      • Reads CSV/Excel/PDF using enhanced presets (TRUCKING_LOAD).
      • Produces legs array with load, customer, location, and charge info.
      • Integrates with CreateModal to pre-populate trucking legs and job-level form fields.
    • This is the primary path for importing multi-drop loads from customer/broker exports.

Job & leg display​

  • Job detail pages:
    • Jobs/Show/index.jsx branches into trucking-specific subviews.
    • Jobs/Show/Info/Trucking/LegsInfo.jsx displays legs with route, drop number, and status.
    • Legs are often the “items” of a trucking job (vs service items for serviceRepair).

Status lifecycle (trucking)​

  • Job-level stages for trucking are defined in src/pages/Jobs/job-stages.tsx:
    • New → Pending → En Route → Delivered → Invoiced.
  • These stages:
    • Drive button labels and actions on the job page (e.g., “Start Job”, “Mark Delivered”).
    • Are the statuses dispatchers and the current trucking customer actually see and use today.

3.3 Mobile App​

Data usage​

  • Leg-centric driver workload:

    • Drivers primarily interact with legs, not entire jobs.
    • DriverLoads.tsx:
      • Fetches legs filtered by driverId and date range via useGetLegsQuery.
      • Presents a calendar view plus a list of legs for the selected date.
    • LegCard:
      • Shows key info: load number, origin/destination, appointment date/time, status.

  • Load details:

    • LoadShow.tsx and LoadDetails.tsx:
      • Show detailed data for a given leg/load ID.
      • Tabs for details, documents, and tasks (for trucking).

Status handling​

  • Mobile reflects leg-level status transitions defined in the API and used by scheduler/dispatch.
  • Driver actions (where implemented) update leg status and feed back into the Job/Load view on web.

4. Status & Completeness​

Implemented today​

  • Backend:
    • Robust Job model that supports trucking loads with multiple legs.
    • Leg model capturing route, driver, appointment, and payout details.
    • Modern createJob controller with multi-industry rate handling and legacy leg-creation path.
  • Web:
    • Manual trucking job creation with multiple legs in TruckingJobForm.
    • File-based leg creation via FileProcessor with trucking-specific configs.
    • Job detail views with trucking legs display and summary.
  • Mobile:
    • Driver-focused leg listing (per day) using useGetLegsQuery.
    • Load/leg detail screens with basic info, documents, and tasks.

Partial / early implementations​

  • The modern createJob flow treats legs as a separate concern; some older flows still use legacyCreate directly with legs.
  • File import + manual editing workflows are well-documented on the Service side, but not yet fully reflected in @attunelogic-docs.
  • Mobile currently exposes legs and loads but lacks a fully driver-centric trucking dashboard (still more service-repair biased).

Missing / not implemented​

  • A first-class trucking load quote entity separate from jobs.
  • A unified “Load lifecycle” doc and API that clearly delineates:
    • Quote → Job/Load → Legs → Dispatch → Billing.
  • Advanced routing (traffic-aware ETAs, VRP) and full HOS integration at the leg level.

5. Dependencies & Configuration​

  • Customer config (useCustomerConfig):
    • Determines appType (trucking vs serviceRepair) and rate behavior.
    • Controls features.Job.items.model (whether legs or maintenance/service items are attached).
  • Industry / appType:
    • When appType === "trucking":
      • Jobs behave as loads with legs as items.
      • Trucking forms and leg components are rendered on the web.
      • Mobile uses trucking-specific flows (legs instead of service items).
  • Roles / permissions:
    • Dispatchers and admins create and edit jobs/loads; drivers mostly interact with legs on mobile.
    • API routes are protected with role- and tenant-based middleware.

6. UX Notes & Known Issues​

  • What users experience today:
    • Dispatchers can manually create and edit multi-leg trucking loads or import them from files.
    • Drivers see their assigned legs by date and can view load details/documents.
  • Known rough edges:
    • The distinction between “Job” and “Load” is mostly naming; both map to the same underlying Job model.
    • Legacy and modern job creation flows coexist; behavior can differ slightly depending on entry point.
    • There is no single UI action labeled “Create Load from Quote” for trucking; quotes live more in the job-items/proposal layer.

7. Roadmap Alignment​

  • Relevant roadmap sections:
    • API docs/MASTER_ROADMAP.md – Job management enhancements and trucking industry features.
    • Service docs/MASTER_ROADMAP.md – Job & Leg Creation System and File Processing System (already documented).
    • Mobile docs/MASTER_ROADMAP.md – Trucking implementation status and gaps (driver UX, HOS, fleet).
  • What’s planned vs what exists:
    • Planned: richer fleet and driver management, HOS-aware scheduling, advanced routing, tighter quote→load conversion.
    • Exists: solid load/leg modeling, creation (manual + file-based), and basic driver-facing leg workflows.

8. Testing & Risk​

  • Tests:
    • API:
      • Job model and controller tests (including multi-industry behaviors).
      • Security and multi-tenant tests that indirectly exercise job/leg queries.
    • Service:
      • Tests around job creation, shift/schedule behavior, and some leg-related utilities (see tests/ in Service repo).
    • Mobile:
      • Limited automated tests; behavior largely validated via manual testing today.
  • Risks / edge cases:
    • Legacy vs modern job creation divergence.
    • File import edge cases (incomplete/malformed data) impacting leg creation.
    • Rate configuration errors (client vs global rates) affecting totals per leg.
  • Monitoring:
    • Issues surface via job/leg-related API errors, scheduler anomalies, and driver feedback in production.

9. Current Adoption & Next Steps​

  • Current adoption:
    • Used in production by at least one trucking customer (FC Trucking and Logistics Inc.), primarily from the Job page with a mix of manual entry and file import.
    • Dispatchers and back office staff rely on this flow to represent loads and drops; drivers consume legs mostly via mobile/web job views.
  • Next steps:
    • Clarify “Job vs Load” in both UI and docs so trucking users see a consistent concept.
    • Reduce reliance on legacy job creation by gradually migrating all flows to the modern createJob + legs workflow.
    • Tighten integration with future trucking quote/load-quote designs (Quote → Load → Legs).