mralexsaavedra/spotiarr/spotiarr-bullmq

Activation Contract

Load when defining queues, writing workers, enqueueing jobs, or configuring cron jobs in apps/backend/.

Hard Rules

• Queue singletons initialized in infrastructure/setup/queues.ts. Accessing before init throws AppError(500).
• Enqueue from application/ layer via domain service interface — never directly from presentation/.
• Workers go in infrastructure/workers/ (one file per worker, factory function pattern — not classes).
• Scheduled jobs go in infrastructure/jobs/. No locking mechanism — prevent overlapping at implementation level.
• job.data arrives unvalidated — Zod-parse at worker entry.

Real Queue Names

"track-download-processor"; // getTrackDownloadQueue()
"track-search-processor"; // getTrackSearchQueue()
"feed-sync-queue"; // getFeedSyncQueue()
"catalog-sync-queue"; // getCatalogSyncQueue()

Decision Gates

Worker events to handle: completed (log) · drained (trigger SSE events / library scan) · failed (update entity status → Error, emit SSE).

Gotchas

• No DLQ: jobs are lost after max attempts.
• Job ID collisions: download jobs enqueued rapidly — always use Date.now() suffix.
• Workers may depend on settings not yet initialized — ensure container init order.

References

• Queues setup: apps/backend/src/infrastructure/setup/queues.ts
• Workers: apps/backend/src/infrastructure/workers/
• Jobs (cron): apps/backend/src/infrastructure/jobs/