Skip to main content

Trucking Quotes & Proposals – Current Implementation

1. Overview​

  • Feature name: Trucking Quotes & Proposals
  • Primary users: Sales/dispatch, back-office ops, clients (via emailed proposals)
  • Industries: Primarily service/repair today, with limited trucking-specific behavior
  • What this feature solves today:
    • Allows creating job-level proposals/quotes with line items and sending them to customers.
    • Tracks proposal approval status and client signatures via the Job approval mixin.
    • Provides a basic “quote history” mechanism attached to job items.

At present, there is no dedicated trucking “load quote” entity or a clean, first-class “Quote → Load” conversion path for trucking loads. Quotes are primarily implemented as part of the job items / proposal flow that is more service-oriented, and in practice trucking quoting is often handled outside the system (email/Excel) with AttuneLogic used after a load is already confirmed.

2. Repos & Entry Points​

API (@attunelogic-api)​

  • Mixins
    • src/mixins/quoteMixin.js – Adds quoteHistory to job items and helper methods:
      • createQuoteVersion, getQuoteVersion, getLatestQuote.
  • Job model & approval
    • src/models/Job.js – Job model with:
      • Approval mixin for proposals (approval field with status/history/signature).
  • Job controllers
    • src/controllers/jobs/create.js – Creates jobs (no dedicated quote entity).
    • src/controllers/jobs/items.js – Manages job items (service items/maintenance), used heavily in proposals.
    • src/controllers/jobs/approval.js (via core-features docs) – Handles updating approval state.
  • Items controllers (proposal/quote-specific)
    • src/controllers/items/index.js:
      • sendQuote → sendQuoteEmail – Sends quote/proposal email.
      • fetchClientQuote – Fetches a quote for the client portal when using job items.
      • updateApproval – Updates approval state for items with signatures.
    • src/controllers/items/sendQuoteEmail.js – Builds and emails quote PDFs.
    • src/controllers/items/fetchClientQuote.js – Retrieves quote details for a given job item.
  • Routes
    • src/routes/api/v1/items.js:
      • POST /items/quote (or equivalent) – Send quote email.
      • GET /items/quote/:id – Fetch client quote (exact paths documented in code).
    • Job proposal-related routes described in docs/api/core-features.md:
      • GET /jobs/:id/proposal – Get client proposal.
      • POST /jobs/:id/send-proposal – Send proposal email.
      • PUT /jobs/:id/items-approval – Approve job items.

Web (@attunelogic-service)​

  • Docs (service-oriented)
    • docs/development/service-operations.md – Describes service-side quoting, work orders, and proposals.
    • docs/development/job-management.md – Covers jobs and items; proposals are part of that workflow.
  • UI
    • Jobs-related pages allow:
      • Building job items (parts, labor) used as quote lines.
      • Sending proposals to clients (service-repair more than trucking-specific).
    • Trucking UI currently relies more on rates within jobs/legs than on a separate trucking quote UI.

Mobile (@attunelogic-mobile)​

  • Current state
    • Quotes and proposals are not first-class entities on mobile.
    • Drivers and technicians primarily interact with jobs/legs and execution (not quoting).
    • Any quote-related flows are handled outside the mobile app (web/email).

3. Current Implementation (By Platform)​

3.1 Backend API​

Quote history (quoteMixin)​

  • quoteMixin can be applied to models (e.g., job items) to track historic quote versions:
    • quoteHistory: [ { version, quotedSummary, parts[], quotedHours, quotedServiceFee, partsTotal, hourlyTotal, totalCharges, updatedBy, updatedAt, notes } ].
  • Methods:
    • createQuoteVersion(params):
      • Captures the current pricing state of an item (parts, hours, charges) into a new quoteHistory entry.
    • getQuoteVersion(version):
      • Retrieves a specific quote version.
    • getLatestQuote():
      • Returns the most recent quote version for that item.
  • This is currently used primarily for service job items, not trucking-specific loads.

Job proposals (approval mixin)​

As documented in docs/api/core-features.md:

  • Jobs include an approval subdocument with:
    • status: "pending" | "approved" | "rejected".
    • Signature, reviewer, timestamps, and history.
  • Proposal-related endpoints:
    • GET /jobs/:id/proposal – Fetch a job’s proposal for client viewing.
    • POST /jobs/:id/send-proposal – Send proposal email with PDF.
    • PUT /jobs/:id/items-approval – Approve items (often tied to quotes).
  • This mechanism works for both industries but is more fleshed out for service/repair (where line items and work orders map well to proposals).

Items-based quotes​

  • items/index.js exposes:
    • sendQuote – Wraps sendQuoteEmail, builds an email with the current state of the job item as a quote.
    • fetchClientQuote – Retrieves an item’s quote for the client portal, including quoteHistory.
  • Quotes here are essentially service-items quotes (parts and labor), not trucking load quotes.

3.2 Web App (Service)​

  • The web app uses:
    • Job items + proposal sending for service quotes/estimates (e.g., parts + labor for an HVAC job).
    • Job approval workflows to track client acceptance.
  • For trucking:
    • Sales/rates are typically managed via job/leg rate fields (base/fuel/flat) and via imported data.
    • There is no specialized trucking quote UI that:
      • Creates a quote separate from a job/load.
      • Lets users explicitly convert a trucking quote into a Job/Load.

3.3 Mobile App​

  • Mobile currently does not expose quote/proposal flows.
    • There are no screens/routes dedicated to creating or reviewing quotes.
    • Acceptance and financial discussions occur via web/email, not in app.

4. Status & Completeness​

Implemented today​

  • API & Service:
    • Jobs support proposals and approval workflows with PDF/email integration.
    • Job items (especially in service/repair) can maintain quoteHistory through quoteMixin.
    • Endpoints exist to:
      • Fetch proposals (/jobs/:id/proposal).
      • Send proposal emails (/jobs/:id/send-proposal, items.sendQuote).
      • Approve/reject items (items.updateApproval, job approval routes).
  • Mobile:
    • No direct support for viewing or acting on quotes; workflows are job/leg execution-centric.

Partial / early implementations​

  • The quote/proposal system is general-purpose but service-oriented:
    • It can technically be used for trucking, but:
      • Fields and templates are more tailored to service jobs.
      • There is no dedicated trucking rate quote/bid workflow.
  • Job approval and quoteHistory are capable of supporting more advanced quoting behaviors but are not yet unified into a clean “Quote entity”.

Missing / not implemented​

  • No first-class Quote model for trucking loads:
    • No entity with fields like lane, equipmentType, trucking-specific surcharges, etc., distinct from Job.
    • No clean POST /quotes → POST /quotes/:id/accept → POST /quotes/:id/convert-to-job flow.
  • No explicit “Quote → Load/Job” conversion logic:
    • Today, users effectively create jobs directly with rates, or use proposals around job items.
    • The system does not track “this job/load came from quote X” in a dedicated trucking context.
  • No mobile support for quote review/acceptance.

5. Dependencies & Configuration​

  • Customer config (useCustomerConfig):
    • Controls which model is used for job items (features.Job.items.model) and thus where quoteMixin applies.
    • Determines industry behavior (appType) and which templates are used for proposals.
  • Industry / appType:
    • serviceRepair:
      • Proposal + quote functionality is more directly useful (estimates, work orders).
    • trucking:
      • Primarily uses job/leg rate fields; proposals exist but are not a clear “load quote” path.
  • Roles / permissions:
    • Only authenticated users with appropriate roles can send quotes/proposals and update approvals.
    • Client users with tokens can view and approve/reject proposals via client-facing endpoints.

6. UX Notes & Known Issues​

  • What users experience today:
    • Service users:
      • Can build detailed estimates, send proposals, and track approvals.
    • Trucking users:
      • Typically treat jobs/loads as the main “contract”; quotes may be handled externally or via ad-hoc proposals.
  • Known rough edges:
    • There is no single, clearly branded “Trucking Quote” workflow:
      • Different parts of the system (rates on jobs, job items, emails, PDFs) contribute, but there is no unified UX.
    • The relationship between proposals and trucking loads is implicit; there’s no automatic conversion that creates a Job/Load with legs from a trucking quote entity.

7. Roadmap Alignment​

  • Relevant roadmap sections:
    • API docs/MASTER_ROADMAP.md – PDF & Job Management improvements mention proposals and approval workflows.
    • Service docs/MASTER_ROADMAP.md – Financial tools and estimate generation for trucking and service.
    • Mobile docs/MASTER_ROADMAP.md – Future customer communication and load documentation features (but not a full quote flow yet).
  • What’s planned vs what exists:
    • Planned:
      • More structured financial tools, tighter integration between rate calculation and load management.
      • Customer portals and possibly internal quote dashboards.
    • Exists:
      • A robust job/proposal system for service jobs, with emails and PDFs.
      • Trucking-related rates handled on jobs/legs, but without a dedicated “load quote” entity or conversion flow.

8. Testing & Risk​

  • Tests:
    • There are tests around:
      • Job approval workflows and security (especially around client tokens).
      • PDF generation and email sending pipelines.
    • There is no dedicated “Quote” test suite for trucking; behavior is validated via job/item/proposal tests.
  • Risks / edge cases:
    • Because trucking quoting is not a first-class entity, different teams may:
      • Use proposals inconsistently.
      • Rely on external spreadsheets or emails for rate quoting.
    • Future introduction of a true Quote model will require:
      • Careful migration and backward compatibility considerations.
      • Clear mapping from existing proposal/approval data.
  • Monitoring:
    • Quote/proposal issues surface primarily through:
      • Email/PDF problems.
      • Approval mismatch or missing history.
      • Business complaints about lack of a clean quote→load path for trucking.

9. Current Adoption & Next Steps​

  • Current adoption:
    • Service/repair teams can and do use proposals and quotes as part of their standard workflow.
    • Trucking teams typically negotiate and confirm rates outside the system (email/Excel) and then create jobs/loads directly in AttuneLogic once a load is booked.
  • Next steps:
    • Design a first-class trucking Quote/Rate Confirmation entity and UX that feels natural for carriers and brokers.
    • Define and implement a clear Quote → Load/Job conversion flow, including how legs, rates, and references are derived.
    • Keep backward compatibility by mapping existing proposals/approval data into the new flow where appropriate, and ensuring service/repair quoting remains unaffected.