| name | temporal |
| description | Temporal.io SDK concepts and this repo's conventions for workflows, activities, signals/queries/updates, schedules, and worker/client wiring. Triggers on: add a workflow, add an activity, signal handler, query handler, update handler, schedule, worker configuration, connection setup, workflow proxy, Temporal client usage, task queue, retry policy, timeout. |
Temporal.io in this repo
This library wraps @temporalio/client, @temporalio/worker, @temporalio/workflow, @temporalio/common (peer deps, version range in package.json; verify current SDK behavior with the temporal-sdk-researcher subagent before relying on a signature from memory).
Concept decision matrix
| Need | Use | Runs in |
|---|
| Business logic, orchestration, waiting | Workflow | v8 isolate sandbox — deterministic only |
| I/O, DB, HTTP, non-deterministic work | Activity (@Activity/@ActivityMethod, src/decorators/activity.decorator.ts) | Normal Node context, full DI |
| External event pushed into a running workflow | @SignalMethod | Workflow sandbox |
| Read workflow state without mutating it | @QueryMethod | Workflow sandbox |
| Mutate + return a value synchronously | @UpdateMethod | Workflow sandbox |
| Spawn a workflow from another workflow | @ChildWorkflow | Workflow sandbox |
| Recurring/cron-like execution | TemporalScheduleService (src/services/temporal-schedule.service.ts) | Client-side, not sandboxed |
If a change adds/edits workflow code, run the workflow-sandbox-reviewer subagent afterward — sandbox violations (DI, non-determinism) compile fine and only fail at runtime during replay.
Where things live
src/decorators/activity.decorator.ts, src/decorators/workflow.decorator.ts — decorator definitions, write Reflect.defineMetadata on both constructor and prototype (see decorator-metadata-auditor subagent).src/services/temporal.service.ts — public facade; prefer this over reaching for @temporalio/client directly in application code.src/services/temporal-client.service.ts — wraps Client, owns the client-side connection.src/services/temporal-worker.service.ts — worker lifecycle (start/stop/graceful shutdown), tied to NestJS shutdown hooks.src/services/temporal-connection.factory.ts (+ src/providers/temporal-connection.factory.ts) — separate connections for client vs worker; do not share one connection across both.src/services/temporal-discovery.service.ts — scans the Nest module graph via DiscoveryModule for @Activity classes at bootstrap.src/workflow-proxy/ — WorkflowProxyFactory.createProxy<T>({ workflowType, taskQueue }) returns a typed proxy over client.workflow.start; prefer this over hand-rolling client.workflow.start calls in consumer code.src/constants.ts — injection tokens (TEMPORAL_CLIENT, TEMPORAL_CONNECTION, TEMPORAL_MODULE_OPTIONS, WORKER_MODULE_OPTIONS, ACTIVITY_MODULE_OPTIONS), metadata keys (TEMPORAL_ACTIVITY, TEMPORAL_SIGNAL_METHOD, etc.), TIMEOUTS and RETRY_POLICIES presets — reuse these presets instead of inlining new timeout/retry literals.
Conventions
- Timeouts/retries: pull from
TIMEOUTS/RETRY_POLICIES in constants.ts when a preset fits; only add a bespoke value when none of the presets apply.
WorkflowIdConflictPolicy / WorkflowIdReusePolicy enums in constants.ts mirror the SDK's own enums — reuse them rather than importing the SDK enum directly, to keep the public API stable across SDK version bumps.- Before implementing a feature against a
@temporalio/* API you're not certain about, invoke temporal-sdk-researcher rather than assuming the signature — this repo has already shipped a fix for SDK API drift (fix: update Temporal.io dependencies to version 1.19.1).
