Queue and scheduler
Queue jobs
Jobs run on River, a Postgres-backed queue — no Redis required. A job is
a definition registered in a queue.Registry:
func RegisterJob(registry *queue.Registry, driver Driver) error { return registry.Register(queue.Definition{ Kind: KindSend, // "mail.send" Description: "Delivers an email through the configured mail driver.", Queue: queue.QueueDefault, // critical | default | heavy Timeout: time.Minute, SystemJob: true, // no tenant needed Validate: validateSendPayload, // rejects bad payloads at enqueue time Handle: func(ctx context.Context, payload []byte) error { var input sendPayload if err := json.Unmarshal(payload, &input); err != nil { return err } return driver.Send(ctx, Message{To: input.To, Subject: input.Subject, Text: input.Text}) }, })}Register it from internal/app/platform.go (most modules expose RegisterJobs(registry)), so the
API, the worker and the CLI all know the job.
Enqueueing
err := engine.Enqueue(ctx, mail.KindSend, payload, queue.EnqueueOptions{})Prefer EnqueueTx when the job belongs to a write: the job row commits in the same
transaction, so a rolled-back write never sends a mail, and a committed one always does.
err := engine.EnqueueTx(ctx, tx, KindProcessImport, payload, queue.EnqueueOptions{})Tenancy travels with the job
River sees one job kind (ims.job) whose envelope is {kind, payload, tenant_id, branch_id}. The
dispatcher restores the tenant scope before calling your handler, so a tenant job sees exactly
the tenant that enqueued it. A tenant job enqueued without a tenant is refused.
Queues and retries
| Queue | Default tries | Timeout | For |
|---|---|---|---|
critical |
3 | 60 s | must-happen-now work |
default |
5 | 120 s | mail, notifications |
heavy |
1 | 30 min | imports, exports, backups |
Tune with QUEUE_<NAME>_TRIES / _TIMEOUT and QUEUE_WORKER_CONCURRENCY.
Running workers
ims queue:work # run workers until stopped (make queue)ims queue:work --once # drain what's queued, then exitims queue:stats # depth per queue and stateQUEUE_DRIVER=sync runs jobs inline — handy for tests and one-off CLI use. Workers don’t
hot-reload: restart make queue after changing a job. In the dashboard, Queue lists jobs
with their payload envelope and lets you retry, cancel or delete them.
Scheduled tasks
Recurring work is one list in internal/app/schedule.go — Laravel’s Kernel::schedule:
{ ID: "billing.expire-subscriptions", Spec: "0 */6 * * *", // cron, in SCHEDULE_TIMEZONE Description: "Marks overdue subscriptions as expired.", Timeout: 10 * time.Minute, Run: func(ctx context.Context) error { expired, err := p.BillingSubs.ExpireOverdue(ctx) if err != nil { return err } logger.Info("subscriptions expired", "count", expired) return nil },},- Overlapping runs are skipped by default; set
Overlap: scheduler.OverlapAllowto allow them. - Tasks that depend on a feature are appended only when it is enabled (backups, the database cache, the dashboard).
- Only one scheduler runs per database (a Postgres advisory lock), so starting two by mistake is harmless.
ims schedule # run the scheduler (make schedule)ims schedule:list # every task with its specims schedule:run <id> # run one task nowThe built-in tasks
| Task | When | Does |
|---|---|---|
scheduler.heartbeat |
every minute | records liveness for /api/health |
dataprocessing.cleanup-completed |
02:00 | deletes old completed import/export jobs |
notifications.purge-expired |
03:30 | deletes notifications expired over 7 days ago |
billing.expire-subscriptions |
every 6 h | expires overdue subscriptions |
billing.send-renewal-reminders |
08:00 | reminders at 7, 3 and 1 days before expiry |
activity.prune |
03:45 | applies ACTIVITY_RETENTION_DAYS |
cache.purge-expired |
hourly :15 | database cache driver only |
backup.run, backup.clean |
BACKUP_RUN_CRON, BACKUP_CLEAN_CRON |
when backups are enabled |
devdashboard.prune |
03:00 | telemetry and dashboard audit retention |
The heartbeat lives in the cache. With CACHE_DRIVER=memory it is only visible inside the
scheduler process, so the API’s health check can’t see it — use database or redis anywhere
the API and scheduler run as separate processes.

