trails-cool/trails
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
trails/openspec/changes/pg-boss-background-jobs/proposal.md
Ullrich Schäfer 32c5fbde8f Add pg-boss background job queue with session expiry 
Add @trails-cool/jobs package wrapping pg-boss for durable background job
execution using the existing PostgreSQL database. Wire up planner session
expiry as the first scheduled job (hourly, 7-day TTL) — this was previously
dead code that never ran. Add placeholder worker to journal for future
Komoot import and federation jobs.

Infrastructure: grant grafana_reader access to pgboss schema, add job queue
health panels to Service Health dashboard, add failed job alert.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-13 21:17:24 +02:00

1.9 KiB
Raw Blame History

Why

Background work (session expiry, Komoot activity imports) currently has no durable execution mechanism. Session cleanup exists as dead code (expireSessions) that is never called, and the Komoot import in #223 rolls its own ad-hoc background processing without retries or failure handling. Adding pg-boss gives us a PostgreSQL-backed job queue with scheduling, retries, and observability through our existing Grafana stack — no new infrastructure required.

What Changes

  • Add pg-boss as a dependency to both the Planner and Journal apps
  • Create a shared background worker setup in @trails-cool/db (or a new @trails-cool/jobs package) that initializes pg-boss with the existing DATABASE_URL
  • Wire up planner session expiry as the first recurring job (hourly cron, 7-day TTL)
  • Wire up Komoot import processing as a durable job with retries (replaces ad-hoc background processing in #223)
  • Grant grafana_reader SELECT on the pgboss schema for dashboard visibility
  • Add a Grafana dashboard panel for job queue health (queue depth, failed jobs, processing duration)

Capabilities

New Capabilities

  • background-jobs: pg-boss job queue setup, worker lifecycle, job registration, cron scheduling, retry policies, and Grafana observability

Modified Capabilities

  • planner-session: Session expiry is now handled by a scheduled pg-boss job instead of being uncalled dead code
  • infrastructure: PostgreSQL init script grants grafana_reader access to the pgboss schema; Grafana gets a job queue health panel

Impact

  • Dependencies: Adds pg-boss npm package
  • Database: pg-boss auto-creates its schema (pgboss) in PostgreSQL on first run
  • Apps: Both planner and journal server entry points start a pg-boss worker
  • Monitoring: New Grafana panel on Service Health dashboard for job queue metrics
  • Komoot import (#223): Will be refactored to use pg-boss instead of ad-hoc background processing