What this is

Swappr has a dedicated worker process (@swappr/worker) that runs separately from the API. It consumes four BullMQ queues for the heavy / scheduled / long-running work that should not block API request handlers. This page covers:
  1. The four queues and what they do.
  2. How both the producer (api) and consumer (worker) sides flip between in-memory stubs and BullMQ on the same REDIS_URL signal.
  3. Scheduling — what runs on cron, what reacts to enqueue.
  4. The graceful shutdown order.
  5. The stub-mode behaviour for pnpm dev and unit tests.
  6. The deferred-at-credentials matrix.
Source of truth: apps/worker/src/index.ts (bootstrap), apps/api/src/index.ts (producer selection), SWAPPR_BACKEND_PLAN §13 + §14.

The four queues

Bootstrap diagram

REDIS_URL — one signal, two sides

The producer and consumer both check the same env var:
  • API process (apps/api/src/index.ts) — resolvePushQueue, resolveRetentionEnqueuer, resolveGdprExportQueue, resolveErasureEnqueuer all key off process.env.REDIS_URL. With it: BullMQ-backed producer. Without it: a no-op enqueuer (returns Promise.resolve() — the API still returns 202 Accepted so the surface looks identical to the caller, but no work happens).
  • Worker process (apps/worker/src/index.ts) — bootWorker({ redisUrl }). With it: constructs all four Worker instances + a shared ioredis connection + schedules the two repeatable jobs. Without it: returns a WorkerHandle in 'no-worker' mode and exits the bootstrap path with a warn log.
This single signal means dev / unit tests just work with no Redis — the entire surface is exercisable, only the actual side-effects (FCM send, S3 delete, ZIP upload, hard delete) are skipped.
The api-side selector is required to inject a queueFactory when REDIS_URL is present (production caller must construct the BullMQ Queue). The selector deliberately throws if REDIS_URL is set but no factory is supplied — fail loud, not silently fall back to no-op when ops thinks BullMQ is wired.

Scheduling — cron vs reactive

The 03:00 / 04:00 offset is intentional — retention runs first so a tenancy document that’s both “30d post-decision” AND “owned by a soft-deleted user” is removed by retention through its dedicated path before erasure sees it. See GDPR data lifecycle.

Graceful shutdown

On SIGTERM or SIGINT the worker process closes resources in order:
  1. Workers (stop accepting new jobs; let in-flight jobs finish to BullMQ’s lockDuration ceiling).
  2. Queues (drain producer-side state).
  3. Shared ioredis connection (.quit() — graceful FIN, not .disconnect()).
The api-side has the parallel shutdown sequence — close the four producer queues, then quit the shared connection. The two processes share the same Redis instance but each owns its own connection.

Stub-mode behaviour

When REDIS_URL is absent: This means a developer can pnpm dev with no Redis installed and the entire HTTP surface works — the only thing missing is the asynchronous side-effects (push notifications, retention cleanup, export ZIP generation, erasure tombstoning).

Deferred at credentials

These are wired up but gated on a production credential that isn’t in Phase 7’s scope: RevenueCat is not in this list — Phase 7 has no RevenueCat worker. The Phase 5 RevenueCat webhook stays in stub mode (BILLING_NOT_CONFIGURED) until the real RevenueCat secret is wired.

Why a separate process?

Three reasons (BACKEND_PLAN §13):
  1. Blast radius. A worker crash from a malformed FCM token, a runaway ZIP, or an S3 hang must not take the API down.
  2. Scaling profile. The API scales on request volume (spiky). The worker scales on queue depth (smoother). They need different deployment knobs.
  3. Deploy cadence. Worker bug fixes (e.g. a new push payload field) can ship without an API redeploy.

See also