Job catalogue

Every async job runs through the same BullMQ queue (scani-jobs), consumed by apps/backend/worker. Wire names live in packages/business/jobs/src/job-names.ts; descriptors in packages/business/jobs/src/scheduled-jobs/ (for repeatable jobs) or packages/business/jobs/src/user-jobs/ (for user-initiated jobs); processors in apps/backend/worker/src/processors/.

Scheduled jobs use the advisory-lock wrapper — two overlapping fires of the same name silently no-op rather than race.

The reconcilers and probes all run on the same quarter-hour cadence on purpose: aligning them means their advisory locks batch into one wake, so the database can scale to zero between runs instead of being nudged awake four times an hour.

Scheduled jobs

Name	Frequency	Purpose
`pricing`	Hourly (`0 * * * *`)	Refresh current prices for every token referenced by an active holding.
`wallet-balances`	Hourly (`0 * * * *`)	Re-sync on-chain wallet balances + transactions across Etherscan, Helius, Bitcoin, Tron, TON.
`exchange-balances`	Hourly (`0 * * * *`)	Re-sync exchange holdings + recent trades for every connected exchange integration.
`exchange-transactions`	Daily (`0 1 * * *`)	Refresh the transaction ledger for every connected exchange/broker/bank integration — fans out a `transaction-import` per account with a 30-day rolling window.
`apy-payouts`	Daily, 00:00 UTC (`0 0 * * *`)	Apply accrued interest to holdings with an APY config due for payout.
`historical-price-backfill`	Nightly, 03:00 UTC (`0 3 * * *`)	Fill `daily`-granularity price history for tokens with holdings; respects `unpriceableUntil` cooldown.
`forex-backfill`	Nightly, 03:30 UTC (`30 3 * * *`)	Fill historical FX pairs (via Frankfurter) needed by the rollup.
`token-prices-downsample`	Nightly, 05:00 UTC (`0 5 * * *`)	Collapse `intraday` prices older than 7 days into one `daily` row per token/base/day (keeps the day’s last reading); preserves existing `daily` and `tx-exact` rows. Caps `token_prices` growth.
`portfolio-value-rollup`	Nightly, 04:00 UTC (`0 4 * * *`)	Recompute `portfolio_value_daily` for every user at user / institution / account / holding scope.
`transfer-linking`	Nightly, 03:45 UTC (`45 3 * * *`)	Pair CEX withdrawals with wallet deposits via `LinkTransferPairsUseCase`.
`backfill-token-identity`	Weekly, Sunday 02:00 UTC (`0 2 * * 0`)	Re-enrich tokens whose `providerMetadata` hasn’t been touched lately.
`backfill-counterparty`	Nightly, 05:30 UTC (`30 5 * * *`)	Extract a counterparty + description onto `holding_transactions` rows that predate the per-provider extractors.
`reconcile-pending-credentials`	Every 15 minutes (`/15 * * *`)	Sweep stuck `pending` integration-credential rows (UI flow interruptions).
`reconcile-orphaned-user-jobs`	Every 15 minutes (`/15 * * *`)	Sweep stuck `running` user-job rows whose worker process died.
`dlq-depth-probe`	Every 15 minutes (`/15 * * *`)	Read the dead-letter queue depth; emit a warn log when it crosses thresholds.
`job-heartbeat-probe`	Every 15 minutes (`/15 * * *`)	Detect jobs whose heartbeat went silent; mark them stuck.
`stale-sync-probe`	Hourly (`0 * * * *`)	Detect active, credentialed integrations that have silently stopped syncing — stale `lastSync` or zero accounts — and alert via Sentry.
`hide-closed-holdings`	Nightly, 04:30 UTC (`30 4 * * *`)	Auto-hide holdings that have been at zero balance for the configured window.
`rescore-scam-tokens`	Nightly, 02:30 UTC (`30 2 * * *`)	Recompute `is_scam_probability` for crypto tokens whose `scam_score_version` is stale, so a change to the scoring heuristic reaches tokens already stored. Non-crypto tokens are `unscored` and never enter the population; rows marked by a person are never recomputed.
`payment-due-reminder`	Hourly (`5 * * * *`)	One Web Push a day at ~17:00 in each user’s own local time, summarising the payments due on their local tomorrow as a count and a per-currency total. Fires hourly and selects only the users for whom it is currently 17:00 locally — a single daily fire happens at one UTC hour, and one UTC hour is a different clock time in every zone. A user whose `users.timezone` is still NULL is SKIPPED, never defaulted to UTC, and counted in the job’s log line. Nothing is sent on a day with nothing due. Needs `VAPID_SUBJECT` / `VAPID_PUBLIC_KEY` / `VAPID_PRIVATE_KEY`; without them the job logs a refusal on every fire and sends nothing.

Scheduled jobs — declared but not registered

A descriptor can exist in packages/business/jobs/src/scheduled-jobs/ without being listed in SCHEDULED_JOB_DESCRIPTORS, and then the worker never registers it: the jobs below do not run. They are listed here because the file is in the tree and a reader who finds it deserves to know which half is missing — not because they are live. The table above is the list of live jobs.

There are none right now. The table below is empty, and that is the correct steady state — a descriptor belongs here only for as long as its processor is unwritten. payment-due-reminder was the last one; it moved to the live table above when PaymentDueReminderProcessor landed in the same commit that registered it (SC-226).

The heading stays even when empty, because scripts/check-docs.ts reads both tables and fails if either is missing — and a page that silently loses the distinction is how a job that never runs gets read as one that does.

Name	Frequency when registered	Blocked on	Purpose

User-initiated jobs

Enqueued by the api in response to a user action. They use a stable per-user job ID so the user can see “in flight” status in the SPA.

Name	Triggered by	Purpose
`screenshot-parse`	Upload a screenshot	Send to OpenAI Vision; materialise the extracted holdings under a manual institution.
`document-parse`	Upload an invoice	Classify the PDF, extract text (OCR only for pages that need it), then read vendor / amount / dates via the AI provider. Lands in the review feed for confirmation.
`exchange-import`	Connect an exchange	First-time backfill: sync balances + transactions; create accounts/holdings.
`wallet-import`	Add a wallet	First-time backfill: scan the address across the chain; create holdings.
`file-import`	Upload a CSV / file	Parse and ingest.
`holding-price-update`	User edits a private-token price	Persist the new price + audit row in `token_price_edit_history`.
`refresh-account-balance`	User triggers a manual sync	Force-refresh one account’s balances + transactions.
`manual-holdings-create`	User creates a manual holding	Insert under the manual institution; seed observation.
`portfolio-history-backfill`	After import / manual edit	Rebuild `portfolio_value_daily` for the affected date range for one user.
`currency-rate-refresh`	A read path needed a currency pair storage could not answer	Fetch the pair off the request. The upstream call sits behind a two-per-sixty-seconds limiter whose acquire sleeps, so on a read path the third uncovered currency waited ~26 s; here nobody waits. The figure renders without the pair and says so, and the next read has it (SC-222).
`transaction-import`	(Reserved)	One-off transaction-only import flow.
`user-data-delete`	User requests account / data deletion	Delete (or export, depending on the flag) all user data per GDPR-style flow.

Retry policies

Defined in packages/business/jobs/src/retry-policies.ts:

Policy	Shape	Default for
`standard`	5 attempts, exponential backoff, 60s base.	Most scheduled jobs.
`aggressive`	10 attempts, exponential, 5s base.	Reconcilers (`reconcile-pending-credentials`, `reconcile-orphaned-user-jobs`).
`none`	1 attempt.	Probes (`dlq-depth-probe`, `job-heartbeat-probe`).
`user-import`	3 attempts, longer base.	User-import jobs — fail fast so the user can re-try.

DLQ (dead-letter queue)

Jobs that exhaust their retries land in scani-dlq. The dlq-depth-probe job alarms when depth grows. Operators replay via the HMAC-gated jobs.dlqReplay endpoint on the api.

Adding a job

See Adding a scheduled job for the three-place change required.