Background Jobs

TimeTiles uses Payload CMS’s built-in job queue for all asynchronous processing. Jobs are defined in lib/jobs/ and registered in lib/config/payload-shared-config.ts.

Key Behavior

Auto-deletion: Completed jobs are automatically deleted (deleteJobOnComplete: true)
Hook-driven queueing: Jobs are queued by collection afterChange hooks via StageTransitionService, not manually
Single process: Jobs run in the same Node.js process as the web server (no separate worker)

Import Pipeline Jobs

These 8 jobs process files through the import pipeline sequentially. See Data Processing Pipeline for detailed stage documentation.

Job	Purpose	Trigger
`dataset-detection`	Parse file, create import jobs per sheet	File upload to `import-files`
`analyze-duplicates`	Find internal/external duplicate rows	Stage transition
`schema-detection`	Build progressive JSON Schema from data	Stage transition
`validate-schema`	Compare detected vs existing schema	Stage transition
`create-schema-version`	Persist approved schema version	Approval or auto-approve
`geocode-batch`	Geocode unique locations via providers	Stage transition
`create-events-batch`	Create event records in database	Stage transition

Scheduled Import Jobs

Job	Purpose	Trigger
`schedule-manager`	Check cron schedules, trigger due imports	Periodic (runs on interval)
`url-fetch`	Download file from URL for scheduled import	Schedule manager
`cleanup-stuck-scheduled-imports`	Reset imports stuck in processing state	Periodic
`process-pending-retries`	Retry failed imports with exponential backoff	Periodic
`cleanup-approval-locks`	Release stale approval locks	Periodic

System Maintenance Jobs

Job	Purpose	Trigger
`quota-reset`	Reset daily user quota counters (midnight UTC)	Periodic
`cache-cleanup`	Clean expired cache entries	Periodic
`schema-maintenance`	Clean up orphaned schema versions	Periodic
`audit-log-ip-cleanup`	Clear IP addresses older than 30 days (privacy)	Periodic
`data-export`	Generate ZIP archive of user data	User request
`data-export-cleanup`	Delete expired export files	Periodic
`execute-account-deletion`	Process scheduled account deletions after grace period	Periodic

Adding a New Job

Create handler in lib/jobs/handlers/my-job.ts
Export job config from lib/jobs/import-jobs.ts
Add to ALL_JOBS array in lib/config/payload-shared-config.ts
Create migration if the job needs new fields

Testing Jobs

See Integration Testing Patterns for job testing. Key points:

Query pending jobs before running (completedAt: { exists: false })
Verify side effects after running (not job records — they’re deleted)
Use describe.sequential() for tests that interact with the job queue