How Omazy runs work in the background.

Section 01 · executive tl;dr

The 60-second read.

For C-level and cross-functional readers. The whole platform in five lines.

Section 02 · how it works

One platform, in one diagram.

Producers call a typed enqueue. Tasks land in Redis under one of three priority queues. The Asynq server in the API binary pulls them and runs the registered handler. Retries, scheduling, and observability come for free.

Section 03 · queues

Three priority queues, one worker pool.

The worker thread always picks the highest-priority pending task. The 6:3:1 ratio means analytics work never starves, but auth never waits behind it.

• ·01

  Zero new infrastructure

  Redis is already deployed via Docker on the existing droplet. Asynq rides on the same connection. No second cluster to operate, monitor, or pay for.

• ·02

  Type-safe producers

  A closed catalogue of TaskKind constants. Producers compile against the registry; typos are rejected at runtime. No silent dropped tasks.

• ·03

  Three priority queues

  critical (auth, audit) · default (most work) · low (analytics, reconciliation). Weight ratio 6:3:1 — the worker thread always picks the highest-priority pending task.

• ·04

  Retries + backoff baked in

  Default 25 retries with exponential backoff per task. Permanent failures opt out via SkipRetry. Per-spec overrides for short-lived work.

• ·05

  Scheduled tasks + cron

  Five-field cron syntax or @every shorthand. One-shot delays via ProcessIn. Already powers the analytics drain (every 30s) and custom-domain checks (hourly).

• ·06

  Trace context propagation

  OpenTelemetry span IDs ride on the task payload. A single trace covers HTTP → enqueue → handler → retries → completion. No grepping logs.

• ·07

  Boot-time validation

  Unknown TaskKind, duplicate registration, or a nil handler — the server panics at start. Programmer errors fail loud, not at 3 a.m.

• ·08

  Admin inspector, no extra UI

  GET /api/v1/admin/jobs/* exposes queue depth, per-task state, retry, delete. Audited. Zero dashboard to deploy.

• ·09

  Driver-abstraction friendly

  Workers consume Go interfaces (EmailSender, StorageDriver). Swapping Resend → SES touches one factory case, not the workers.

• ·10

  Test-friendly NopClient

  jobs.NopClient() makes Enqueue a no-op. Unit tests exercise handlers in isolation. Redis is not a test dependency.

Section 05 · adding a task

Three files, in this order.

The boot-time validator panics if any step is skipped. There is no missing-fourth-step. By design.

TaskFeedbackEmail TaskKind = "feedback:email"

func (w *Worker) HandleEmail(ctx context.Context, t *asynq.Task) error { ... }

jobs.RegisterSpec(jobs.TaskSpec{ Kind: jobs.TaskFeedbackEmail, Queue: jobs.QueueLow, ... })

Section 06 · monitor

Five endpoints, no separate dashboard.

Queue depth, per-task state, retry, delete — all over plain HTTP, all audited, all already running on production. Wire alerts directly off these; don't build a queue UI.

Section 07 · debug

When something didn't happen.

Walk this in order. Most reports of "X didn't run" are upstream of the queue, not inside it.

1. Was the task ever enqueued? Check the producer's logs or /admin/jobs?state=completed for the task ID. If it's missing, the producer didn't fire — fix the upstream code path, not the queue.
2. Did it run? /admin/jobs/:queue/:id shows state + completed_at. archived = exhausted retries; read last_err.
3. Stuck pending? Pending for minutes means the worker isn't pulling. Check redis: healthy on /health and the asynq server started line in boot logs.
4. Did the side effect occur? Container up ≠ feature works. For email, verify it landed in the inbox; for storage, retrieve the object. Logs are necessary, not sufficient.

Section 08 · gaps

Honest limitations.

None are blockers. Each has a workaround that fits inside Asynq + Redis. Listed so we don't kid ourselves.