Architecture Decision RecordsADR-0004: Temporal for Durable Work

ADR-0004: Temporal for Durable Work

Status

Accepted

Context

We need a reliable way to handle background jobs that require durability, retries, and long execution times (image processing, email sending, data imports). Traditional job queues lack workflow orchestration and visibility.

Decision

Use Temporal (Go SDK) for all background work that is durable, retryable, or takes longer than 500ms. This includes:

  • Image processing (bimg/libvips)
  • Email delivery (Postmark)
  • PDF generation
  • Multi-step business workflows

Consequences

Positive

  • Built-in retry policies, timeouts, and heartbeats
  • Workflow execution history provides full visibility and debuggability
  • Temporal UI for monitoring workflow states
  • Deterministic workflow replay for testing

Negative

  • Additional infrastructure (Temporal Server)
  • Learning curve for Temporal’s programming model
  • Workflows must be deterministic — no I/O in workflow functions
ADR-0003: Next.js BFF PatternADR-0005: OpenAPI Contract-First