Skip to content

ADR-0006: Worker with queues and work discovery per company

  • Status: Accepted
  • Date: 2026-11-13

Sending messages, running automation actions, sequence steps, interview reminders, signed PDFs, audit exports and the daily compliance pass all happen outside a request. A separate worker process with queues in Redis was part of the initial architecture (2026-11-12).

The worker has no session. Under row level security (ADR-0002) it cannot scan a business table for due rows of all companies. How does it find its work?

  • The worker obeys the same isolation as the API: no privilege to bypass row level security.
  • Work that was committed must not be lost if a queue entry is lost.
  • A company with a long backlog must not hold the others.
  1. A scheduled pass per kind of work: a database function returns the companies that have due work, and the worker opens one transaction per company.
  2. A worker role that bypasses row level security and scans every company. Rejected: no routine reads a business table without a company context.
  3. One queue job per piece of work, created when the row is written, with the queue as the only record of what is pending. Obvious alternative, listed for comparison.

Chosen option: 1.

apps/worker hosts the job modules exported by the API code base and uses BullMQ on Redis. Each routine is a job scheduler that runs a pass at a fixed interval. A pass calls gate.tenants_with_due_work(kind) outside any company context. The function returns only the ids of active companies that have due work of that kind, refuses a transaction that already has a context and fails on an unknown kind. Its owner role reads only tenant_id and the status and due-time columns of the tables involved, never the body of a message or of an event. For each id returned, the worker opens a transaction with the context of that company and no user, and does the work under the same policies as the API.

The database is the record of what is pending. A writer only commits its row, and the next pass finds it.

  • Good, because the worker reads business data only inside one company at a time.
  • Good, because losing the content of Redis does not lose work: pending rows are found again by the next pass.
  • Good, because work is taken company by company. The event dispatcher, for example, opens several companies at a time and limits the batches of each one per pass, so one backlog does not stop the rest.
  • Bad, because discovery is polling. The delay of a piece of work is bounded by the interval of its pass (one second for outgoing messages), and the discovery queries run even when nothing is due.
  • Bad, because every new kind of routine needs a new branch in the database function, through a migration.
  • Bad, because a message or an event pending for more than 35 days is no longer returned by the discovery. The daily maintenance routine logs a warning for the events in that state.
  • apps/api/src/core/events/due-work.ts: DueWorkTenants, the discovery used by every routine.
  • packages/db/src/gate.ts: dueWorkKinds, the kinds of work, and tenantsWithDueWork.
  • packages/db/migrations/0038_wave03_automation_functions.sql and 0051_wave04_public_functions.sql: the function.
  • apps/api/src/modules/platform-messaging/send-queue.runner.ts: an example of a pass.
  • Concept page: Background work.
  • Related: ADR-0003, ADR-0025.