Skip to main content

Job Feature Lifecycle (Start to Finish)

This document describes the end-to-end lifecycle of a Job in Attune Logic — from creation to completion, invoicing, and post-close reporting. The exact steps vary by industry / appType (Trucking vs Service/Repair), but the lifecycle pattern is consistent.

1) Creation (Job is born)​

  • Entry points
    • Web app (@attunelogic-service): Jobs are commonly created via the Job Create flow (modal-driven).
    • Scheduler / Dispatch: Creating a scheduled “event” can create a Job (and later updates schedule fields and assignments).
  • Initial data
    • Client (who the work is for)
    • Industry identifiers
      • Trucking: load/order identifiers (e.g., loadNumber, orderNumber)
      • Service/Repair: appointment fields (date/time), service type, priority
    • Initial status (often “New” or “Pending”, depending on config and workflow)

2) Planning & Scope (make the job actionable)​

Service/Repair (scope = job items / services)​

  • Add job items to define scope (quote/services/parts/labor-like lines)
  • Some workflows require approval (quote approval → work execution)
  • Build out operational fields (notes, original call, customer instructions, etc.)

Trucking (scope = legs + routing + charges)​

  • Add one or many legs (stops/deliveries) for multi-stop loads
  • Legs drive routing/mileage and charge calculations
  • Confirm pricing source (global vs client rates; flat vs per-mile where applicable)

See: docs/developer/features/trucking-loads-and-legs.md and (web-app deep dive) @attunelogic-service/docs/JOB_LEG_CREATION.md

3) Pricing & Documents (quote / proposal phase)​

  • Service/Repair
    • Roll up totals (labor, fees, parts, accessories, tax)
    • Send proposal / work order documents to customer (where configured)
  • Trucking
    • Compute charges based on mileage and rate model
    • Confirm accessorials and final totals

4) Dispatch, Scheduling, and Assignment​

  • Assign the Job to resources:
    • Service/Repair: technicians
    • Trucking: drivers (and sometimes leg-level assignment rules)
  • Scheduler updates may adjust:
    • start/end time windows, appointment date/time
    • assigned resources
    • status transitions depending on workflow rules

5) Execution (stage/status progression)​

Jobs progress through configured stages. UI behavior (available actions, validations, modals) is status-dependent and appType-dependent.

Trucking status canonicalization (important)​

Trucking uses canonical snake_case status values for Jobs/Legs and normalizes legacy spellings for backward compatibility.

See: docs/developer/development/trucking-status-canonicalization.md

Typical lifecycle shape (conceptual)​

New/Pending → Booked/Scheduled → Assigned → In Progress / En Route → Completed → Invoiced → Archived

During execution, common updates include​

  • appointment/ETA adjustments
  • assigned resources changes
  • field notes and customer updates
  • items/legs updates (completion, adjustments, media attachments)

6) Activity layer (tasks, notes, timeline)​

Throughout the lifecycle, Jobs can have attached operational features:

  • Tasks
    • job-scoped task lists (and optional task templates/groups)
  • Notes / Activity
    • operational notes, internal communication, history
  • Timeline
    • status changes and meaningful activity used for UI and traceability

7) Closeout (completion + invoicing)​

  • Transition Job to Completed
  • Finalize totals and attach required proof (photos, signatures, POD/BOL, etc.)
  • Create Invoice (where applicable)
    • Job links to Invoice (e.g., an invoiceId reference)

8) Post-close reporting & analytics​

Closed jobs feed reporting and operational analytics, such as:

  • completion rates and cycle time
  • driver/technician utilization
  • dispatch performance and schedule adherence
  • client history and repeat work patterns

9) Tenant + security context (always on)​

Across the lifecycle, access and behavior are governed by:

  • Auth / roles (who can create, edit, dispatch, approve, invoice)
  • Customer config and appType (which stages exist, required fields, validations)
  • Multi-tenant isolation (all job data scoped to a parent company / tenant)
  • docs/developer/development/job-management.md
  • docs/developer/api/job-items-status-management.md
  • docs/developer/features/trucking-loads-and-legs.md
  • docs/developer/features/trucking-dispatch-driver-workflow.md