Customer Lifecycle

The Customer Lifecycle Workflow is the primary business process in Taskr, orchestrating the flow from initial customer request through work completion and payment.

Overview

Flow: Purchase Order → Quote → Job → Invoice → Payment Implementation: packages/workbooks-jobs/src/workflows/customer-lifecycle-workflow.ts Trigger.dev Task ID: customer-lifecycle-workflow

Workflow Stages

type CustomerLifecycleStage =
  | "quote_draft"        // Initial quote creation
  | "quote_sent"         // Quote sent to customer
  | "quote_viewed"       // Customer has viewed quote
  | "quote_approved"     // Customer approved quote
  | "quote_rejected"     // Customer rejected quote
  | "quote_expired"      // Quote expired without response
  | "job_created"        // Job created from approved quote
  | "job_scheduled"      // Job scheduled with technician
  | "job_in_progress"    // Work is being performed
  | "job_completed"      // Work completed successfully
  | "job_failed"         // Work failed - fault created
  | "invoice_generated"  // Invoice created for completed work
  | "invoice_sent"       // Invoice sent to customer
  | "payment_received"   // Payment received and processed
  | "lifecycle_complete"; // Full cycle completed

Workflow Diagram

Workflow Paths

Standard Path
Direct Path
Link Path

PO → Quote → Job → Invoice

The most common path for new customer work requests.

Purchase Order

Customer submits purchase order, which is reviewed and approved.

Quote Creation

Quote created with line items, sent to customer for approval.

Quote Approval

Customer views and accepts quote, triggering job creation.

Job Execution

Job is scheduled, assigned to technician, and completed.

Invoicing

Invoice generated from job, sent to customer.

Payment

Payment received and matched via bank sync.

Typical Duration: 2-8 weeks

Stage Handlers

Quote Handlers

handleQuoteDraft

async function handleQuoteDraft(db: Database, payload: WorkflowPayload): Promise<WorkflowResult> {
  const [quote] = await db.select().from(workbooksQuotes)
    .where(and(eq(workbooksQuotes.id, payload.quoteId), eq(workbooksQuotes.teamId, payload.teamId)));
  
  if (!quote) {
    return { success: false, stage: "quote_draft", message: "Quote not found" };
  }
  
  if (payload.autoProgressEnabled) {
    await triggerWorkflowTransition({ ...payload, currentStage: "quote_sent" });
  }
  
  return {
    success: true,
    stage: "quote_draft",
    nextStage: "quote_sent",
    actions: [{ type: "notification", target: "team", data: { message: `Quote ready` } }]
  };
}

handleQuoteApproved

async function handleQuoteApproved(db: Database, payload: WorkflowPayload): Promise<WorkflowResult> {
  await db.update(workbooksQuotes)
    .set({ status: "accepted", acceptedAt: new Date().toISOString() })
    .where(eq(workbooksQuotes.id, payload.quoteId!));
  
  await triggerWorkflowTransition({
    ...payload,
    currentStage: "job_created",
    stageData: { sourceQuoteId: payload.quoteId }
  });
  
  return {
    success: true,
    stage: "quote_approved",
    nextStage: "job_created",
    actions: [{ type: "notification", target: "team", data: { message: "Quote approved! Creating job..." } }]
  };
}

Job Handlers

handleJobCreated

async function handleJobCreated(db: Database, payload: WorkflowPayload): Promise<WorkflowResult> {
  const jobNumber = `JOB-${Date.now()}`;
  
  const [job] = await db.insert(workbooksJobs).values({
    teamId: payload.teamId,
    customerId: payload.customerId,
    jobNumber,
    title: payload.stageData?.jobTitle,
    status: "draft",
    meta: { sourceQuoteId: payload.quoteId, workflow: { stage: "job_created" } }
  }).returning();
  
  await db.update(workbooksQuotes)
    .set({ status: "converted", convertedJobId: job.id })
    .where(eq(workbooksQuotes.id, payload.quoteId!));
  
  return { success: true, stage: "job_created", nextStage: "job_scheduled", entityId: job.id };
}

Database Schema

Key Tables

-- Purchase Orders
CREATE TABLE workbooks_purchase_orders (
  id UUID PRIMARY KEY,
  po_number TEXT NOT NULL UNIQUE,
  status workbooks_purchase_order_status DEFAULT 'draft',
  customer_id UUID NOT NULL,
  converted_quote_id UUID,  -- Forward link
  converted_job_id UUID,    -- Forward link (direct path)
);

-- Quotes
CREATE TABLE workbooks_quotes (
  id UUID PRIMARY KEY,
  quote_number TEXT NOT NULL,
  status workbooks_quote_status DEFAULT 'draft',
  source_purchase_order_id UUID,  -- Backward link
  converted_job_id UUID,          -- Forward link
);

-- Jobs
CREATE TABLE workbooks_jobs (
  id UUID PRIMARY KEY,
  job_number TEXT NOT NULL,
  status workbooks_job_status DEFAULT 'draft',
  source_quote_id UUID,           -- Backward link
  source_purchase_order_id UUID,  -- Backward link
  invoice_id UUID,                -- Forward link
);

-- Invoices
CREATE TABLE invoices (
  id UUID PRIMARY KEY,
  invoice_number TEXT,
  status invoice_status DEFAULT 'draft',
  source_job_id UUID,  -- Backward link
);

API Endpoints

Workflow Chain Retrieval

workflow.getChain({
  entityId: "uuid",
  entityType: "purchase_order" | "quote" | "job" | "invoice"
})

// Returns:
{
  purchaseOrder?: WorkflowEntity,
  quote?: WorkflowEntity,
  job?: WorkflowEntity,
  invoice?: WorkflowEntity
}

Status Transitions

Entity	Endpoint	Valid Transitions
Quote	`quotes.update`	draft → sent → viewed → accepted/rejected/expired
Job	`workbooksJobs.updateStatus`	draft → scheduled → in_progress → completed
Invoice	`invoices.update`	draft → unpaid → paid

Notifications

Stage	Customer	Team	Technician
quote_sent	Email with quote link	-	-
quote_viewed	-	Dashboard notification	-
quote_approved	Confirmation email	High-priority notification	-
job_scheduled	Appointment confirmation	-	Job assigned notification
job_in_progress	Optional SMS	-	-
job_completed	Completion notification	-	-
invoice_sent	Invoice email	-	-
payment_received	Receipt email	Payment notification	-

Error Handling

Retry Configuration

const customerLifecycleWorkflow = task({
  retry: {
    maxAttempts: 3,
    factor: 2,
    minTimeoutInMs: 1000,
    maxTimeoutInMs: 30_000
  },
  queue: {
    concurrencyLimit: 10
  }
});

Common Failure Scenarios

Scenario	Handling
Quote not found	Return error, don’t progress
Customer email bounced	Retry, then mark for manual follow-up
Payment failed	Move to overdue, send reminder
Job creation failed	Rollback quote status, alert team

Testing

# Integration tests
cd apps/workbooks-api
bun test src/__tests__/integration/customer-lifecycle.test.ts

Fault Resolution

Handle issues discovered during jobs

Job Scheduler

Automated job creation and assignment

Status Reference

All entity statuses and transitions

Invoice Payment

Billing and payment reconciliation

Developer - Overview

Core Workflows

Billing & Subscriptions

Integrations

Team Management

Onboarding Wizards

Reference

Overview

Workflow Stages

Workflow Diagram

Workflow Paths

PO → Quote → Job → Invoice

PO → Job (Skip Quote)

PO → Existing Job

Stage Handlers

Quote Handlers

Job Handlers

Database Schema

Key Tables

API Endpoints

Workflow Chain Retrieval

Status Transitions

Notifications

Error Handling

Retry Configuration

Common Failure Scenarios

Testing

Fault Resolution

Job Scheduler

Status Reference

Invoice Payment

​Overview

​Workflow Stages

​Workflow Diagram

​Workflow Paths

​PO → Quote → Job → Invoice

​PO → Job (Skip Quote)

​PO → Existing Job

​Stage Handlers

​Quote Handlers

​Job Handlers

​Database Schema

​Key Tables

​API Endpoints

​Workflow Chain Retrieval

​Status Transitions

​Notifications

​Error Handling

​Retry Configuration

​Common Failure Scenarios

​Testing

​Related Documentation

Fault Resolution

Job Scheduler

Status Reference

Invoice Payment

Overview

Workflow Stages

Workflow Diagram

Workflow Paths

PO → Quote → Job → Invoice

PO → Job (Skip Quote)

PO → Existing Job

Stage Handlers

Quote Handlers

Job Handlers

Database Schema

Key Tables

API Endpoints

Workflow Chain Retrieval

Status Transitions

Notifications

Error Handling

Retry Configuration

Common Failure Scenarios

Testing

Related Documentation