Workflow Orchestration Patterns

Iron Law

NO WORKFLOW WITHOUT DETERMINISM ENFORCEMENT AND IDEMPOTENT ACTIVITIES — non-deterministic workflow code causes replay failures; non-idempotent activities cause duplicate charges, double-sends, and data corruption

Workflow Orchestration Patterns — Temporal + Java 21 / Python 3.14 / NestJS 11.x

Quick Scaffold

# Start Temporal server locally (Docker)
docker run -d --name temporal \
  -p 7233:7233 -p 8080:8080 \
  temporalio/auto-setup:1.24

# Java 21 / Spring Boot — add to pom.xml
# io.temporal:temporal-sdk:1.25.0
# io.temporal:temporal-spring-boot-autoconfigure-alpha:0.6.0

# Python 3.14 — uv add
uv add temporalio==1.7.0 fastapi uvicorn

# NestJS 11.x — npm
npm install @temporalio/client @temporalio/worker @temporalio/workflow @temporalio/activity

Process

1. Deploy Temporal — local Docker or Temporal Cloud (cloud.temporal.io)
2. Define Activities — external interactions (API calls, DB writes, emails) — must be idempotent
3. Define Workflow — orchestration logic only — must be deterministic (no I/O, no Date.now(), no random)
4. Configure Retry Policies — initial interval, backoff coefficient, max attempts, non-retryable errors
5. Register Worker — binds workflow + activity implementations to task queues
6. Start Execution — client sends startWorkflow() with typed input
7. Add Signals/Queries — external state mutations (signals) and reads (queries) on running workflows
8. Implement Saga — register compensations BEFORE each step; run in reverse (LIFO) on failure
9. Add Heartbeats — long-running activities must call heartbeat() periodically
10. Write Tests — use Temporal test environment with time-skipping for deterministic test execution

Key Patterns

Workflow vs Activity Decision Rule

Does the code touch an external system? (API, DB, file, email, network)
  YES -> Activity
  NO  -> Workflow (orchestration/decision logic only)

Prohibited in Workflow code:

• new Date() / datetime.now() / LocalDateTime.now() — use Workflow.currentTimeMillis() / workflow.now()
• Math.random() / random.random() — use Workflow.newRandom() / workflow.random()
• HTTP calls, DB queries, file I/O — move to Activity
• Threading, locks, Thread.sleep() — use Workflow.sleep()
• Non-deterministic libraries

Conventions & Rules

For per-SDK implementation templates (Java, Python, NestJS), read reference/implementation-playbook.md

Documentation Sources

Before generating code, consult these sources for current SDK APIs:

Reference Files

Common Commands

# View Temporal Web UI (workflows, history, task queues)
open http://localhost:8080

# Java — run worker
mvn spring-boot:run

# Python — run worker
uvicorn src.main:app --reload &
python -m src.worker   # separate process

# NestJS — run worker
npm run start:worker   # defined in package.json scripts

# Run Temporal test suite (time-skipping enabled)
# Java: mvn test
# Python: pytest -q
# NestJS: npm test

Error Handling

For retry policy templates and non-retryable error classification per SDK, read reference/implementation-playbook.md#retry

Activity retry rule: classify every exception before throwing. Validation errors and business rule violations -> ApplicationFailure.newNonRetryableFailure(). Transient network/timeout errors -> retryable (default).

Workflow failure rule: workflows do not catch activity exceptions unless implementing compensation. Let Temporal's retry engine handle transient failures. Only catch ActivityFailure when running saga compensations.

Idempotency rule: every activity MUST be safe to call N times. Use idempotency keys, upsert patterns, and check-then-act with unique constraints. Verify with: "If this activity runs twice with the same input, is the final state identical?"

Post-Code Review

After writing Temporal workflow code, dispatch these reviewer agents:

• architect-review — workflow boundaries, saga completeness, entity lifecycle correctness
• security-reviewer — activity input validation, no secrets in workflow state, payload size limits (2MB)