goplt/docs/content/adr/0024-job-scheduler.md

ADR-0024: Background Job Scheduler

Status

Accepted

Context

The platform needs background job processing for:

• Periodic tasks (cron jobs)
• Asynchronous processing
• Long-running operations
• Retry logic for failed jobs

Options considered:

1. asynq (Redis-based) - Simple, feature-rich
2. cron + custom queue - Build our own
3. Kafka consumers - Use event bus
4. External service - AWS SQS, etc.

Decision

Use asynq (Redis-backed) for job scheduling:

1. Cron jobs: github.com/robfig/cron/v3 for periodic tasks
2. Job queue: github.com/hibiken/asynq for async jobs
3. Storage: Redis (shared with cache)
4. Features: Retries, backoff, job status tracking

Rationale:

• Simple, Redis-backed (no new infrastructure)
• Good Go library support
• Built-in retry and backoff
• Job status tracking
• Easy to integrate
• Can scale horizontally (multiple workers)

Consequences

Positive

• Simple (uses existing Redis)
• Feature-rich (retries, backoff)
• Good performance
• Easy to scale
• Job status tracking

Negative

• Tied to Redis (but we're already using it)
• Requires Redis to be available

Implementation Notes

• Install: github.com/hibiken/asynq and github.com/robfig/cron/v3
• Create pkg/scheduler/scheduler.go interface
• Implement internal/infra/scheduler/asynq_scheduler.go
• Register jobs in internal/infra/scheduler/job_registry.go
• Start worker in fx lifecycle
• Configure retry policies (exponential backoff)
• Add job monitoring endpoint