Workflow Documentation

packages/workbooks-jobs/src/workflows/
├── customer-lifecycle-workflow.ts    # Main orchestrator (Trigger.dev)
├── job-progress-tracker.ts           # Real-time job progress
├── job-stage-handlers.ts             # Individual stage handlers
└── automated-billing-workflows.ts    # Subscription billing

apps/workbooks-api/src/trpc/routers/
├── workflow.ts                       # Workflow chain traversal API
├── maintenance-workflow.ts           # Asset maintenance workflows
└── compliance-workflow.ts            # Compliance scheduling

// Source fields for backward traversal
job.sourceQuoteId       → Quote that created this job
job.sourcePurchaseOrderId → PO that created this job
quote.sourcePurchaseOrderId → PO that created this quote
invoice.sourceJobId     → Job that created this invoice

// Conversion fields for forward traversal
purchaseOrder.convertedQuoteId → Quote created from PO
purchaseOrder.convertedJobId   → Job created from PO
quote.convertedJobId    → Job created from quote
job.invoiceId           → Invoice created from job

// packages/workbooks-jobs/src/workflows/customer-lifecycle-workflow.ts
export const customerLifecycleWorkflow = task({
  id: "customer-lifecycle-workflow",
  retry: { maxAttempts: 3, factor: 2 },
  queue: { concurrencyLimit: 10 },
}, async (payload: WorkflowPayload): Promise<WorkflowResult> => {
  switch (payload.currentStage) {
    case "quote_draft": return handleQuoteDraft(db, payload);
    case "quote_approved": return handleQuoteApproved(db, payload);
    // ... other stages
  }
});

// apps/workbooks-api/src/trpc/routers/workbooks-jobs.ts
updateStatus: protectedProcedure
  .input(z.object({ id: z.string(), status: jobStatusEnum }))
  .mutation(async ({ ctx, input }) => {
    // Validate transition is allowed
    const validTransitions = getValidTransitions(currentStatus);
    if (!validTransitions.includes(input.status)) {
      throw new TRPCError({ code: "BAD_REQUEST" });
    }
    
    // Update status
    await db.update(workbooksJobs).set({ status: input.status });
    
    // Trigger workflow side effects
    await triggerWorkflowTransition({ ... });
  });

# Run workflow integration tests
cd apps/workbooks-api
bun test src/__tests__/integration/workflow.test.ts