workflows

Overview

Workflows are async tasks processed by background workers. Two runners:

Runner	Use Case	Features
SQS	Simple fire-and-forget tasks	Fast, no dependencies, max 15min delay
Hatchet	Complex workflows needing retries, multi-step, or long delays	Typed outputs, configurable timeouts, observability

Quick Start

1. Add Job Name

// server/src/queue/JobName.ts
export enum JobName {
  // ... existing
  MyNewWorkflow = "my-new-workflow",
}

2. Define Payload & Register

// server/src/queue/workflows.ts

// Add payload type
export type MyNewWorkflowPayload = {
  orgId: string;
  env: AppEnv;
  customerId: string;
  // ... your fields
};

// Add to registry
const workflowRegistry = {
  // ... existing
  myNewWorkflow: {
    jobName: JobName.MyNewWorkflow,
    runner: "sqs",  // or "hatchet"
  } as WorkflowConfig<MyNewWorkflowPayload>,
};

// Add trigger function
export const workflows = {
  // ... existing
  triggerMyNewWorkflow: (payload: MyNewWorkflowPayload, options?: TriggerOptions) =>
    triggerWorkflow({ name: "myNewWorkflow", payload, options }),
};

3. Create Handler

For SQS: See references/SQS.md

For Hatchet: See references/HATCHET.md

4. Trigger from Code

import { workflows } from "@/queue/workflows.js";

await workflows.triggerMyNewWorkflow({
  orgId: ctx.org.id,
  env: ctx.env,
  customerId,
});

// With delay
await workflows.triggerMyNewWorkflow(payload, { delayMs: 5000 });

File Structure

server/src/
├── queue/
│   ├── JobName.ts              # Job name enum
│   ├── workflows.ts            # Registry + triggers
│   └── initWorkers.ts          # SQS message routing
└── internal/.../workflows/
    └── myNewWorkflow/
        ├── myNewWorkflow.ts    # Handler
        └── triggerMyNewWorkflow.ts  # (optional) trigger helper

Required Payload Fields

All workflows must include:

{
  orgId: string;
  env: AppEnv;
  customerId?: string;  // optional but common
}

References

• references/SQS.md - SQS workflow implementation
• references/HATCHET.md - Hatchet workflow implementation