# Background Jobs

> Durable background jobs with the transactional outbox: a job is saved in the same Postgres transaction as the write that needs it, then runs from a queue, with retries, schedules and replay.

*Canonical: https://makerkit.dev/docs/void-cloudflare/outbox/overview*

---

Work that must happen *because* a write happened (send a welcome email after sign-up, purge an organization's events after it's deleted, sync a record to another system) goes through the **outbox**. A job is a row saved in the same Postgres transaction as your write: if the write commits, the job exists and will run; if it rolls back, the job never existed. Nothing is lost between "saved" and "queued", and nothing runs for a write that didn't happen.

```ts
import { db } from 'void/db';

import { welcomeEmail } from '#/jobs/welcome-email.job.ts';
import { getOutbox } from '#/lib/outbox.server.ts';

await getOutbox().transaction(db, async (tx, enqueue) => {
  const [row] = await tx.insert(user).values(input).returning();

  await enqueue(welcomeEmail, { payload: { userId: row.id }, dedupeKey: `welcome:${row.id}` });
});
```

The kit uses `@makerkit/workers-outbox`, bound for you: you define jobs and enqueue them, nothing else.

## How It Runs

1. **Enqueue:** `enqueue` inserts a row in `outbox.job` inside your transaction.
2. **Nudge:** once the transaction commits, the outbox sends the job's id to the `outbox` queue (`queues/outbox.ts`). The consumer claims and runs it within seconds.
3. **Sweep:** every five minutes `crons/outbox.ts` recovers jobs whose worker crashed, runs any whose nudge was lost, and deletes finished jobs after their retention (7 days succeeded, 90 days dead or cancelled).

{% img src="/assets/images/docs/void-cloudflare/outbox-delivery.svg" width="600" height="1150" alt="A transaction commits business data and an outbox job together. A queue nudge or sweep delivers the job; effects can repeat after a crash." /%}

The transaction covers the business write and job row only. It cannot roll back an email or an outside API call.

A job runs **at least once**: a crash between the work and its bookkeeping means it runs again. Write handlers so a second run does no harm ([Jobs](./jobs)).

## Job or Plain Queue?

| Use | When |
|---|---|
| **An outbox job** | The work must follow a database write, and must not be lost or run without it: a purge after a delete, a notification for a committed change, a sync. |
| **`queues.<name>.send()`** (`void/queues`) | Fire-and-forget work with no write to tie it to, where losing a message on a crash is acceptable. The kit's auth emails use the `emails` queue this way. |
| **Neither** | Work that must finish before the response: do it in the request. |

## Files

| File | Owner | What |
|---|---|---|
| `apps/web/config/outbox.config.server.ts` | you | `outboxJobs`: every job the outbox may run |
| `apps/web/jobs/*.job.ts` | you | Your job definitions (any folder works) |
| `apps/web/crons/<name>.ts` | you | A recurring job ([Schedules](./schedules)) |
| `apps/web/lib/outbox.server.ts` | kit | `getOutbox`, `defineOutboxSchedule`, `OutboxEnqueueError` |
| `apps/web/config/kit-outbox-jobs.server.ts` | kit | The kit's own jobs (the daily cleanup's), spread into `outboxJobs` |
| `apps/web/config/outbox.server.ts` | kit | The binding: database, queue, deploy version, logger |
| `apps/web/queues/outbox.ts`, `crons/outbox.ts` | kit | The consumer and the sweep |
| `packages/outbox` (`@kit/outbox`) | kit | Strict enqueue, logging and redaction |

Next: [define and enqueue a job](./jobs), [run one on a schedule](./schedules), [handle failures](./failures), [test it](./testing), [deploy](./deployment).
