Background Jobs & Cron
Relevant source files
The following files were used as context for generating this wiki page:
Hearth uses a background job system to manage periodic and long-running tasks such as sending reminders, performing database backups, ingesting emails, and refreshing asset prices. The system relies on node-cron for internal scheduling and a database-backed queue to ensure job persistence and execution lease management.
Sources: src/instrumentation.ts:43-63, CLAUDE.md:67-73
System Architecture
The background job system consists of two primary components started during the application's instrumentation phase: the Scheduled-Job Ticker and the Job Processor. These components coordinate to transition tasks from cron definitions into executed code.
The Scheduled-Job Ticker
The ticker runs every minute (* * * * *). It evaluates currently configured cron schedules for reminders, backups, and email ingestion. If a schedule matches the current time, the ticker enqueues a job into the BackgroundJob queue. This approach allows changes to cron strings in the application settings to take effect without requiring a server restart.
Sources: src/instrumentation.ts:70-106
The Job Processor
The job processor runs every 20 seconds (*/20 * * * * *). It attempts to claim and execute pending jobs from the database. It uses a "job tick" mechanism that skips a cycle if the previous tick is still running, preventing execution pile-up during database slow-downs.
Sources: src/instrumentation.ts:108-124
Concurrency and Leasing
Hearth prevents concurrent execution of the same job type across multiple instances using a database lease. When a job is claimed, it is guarded against other instances until the lease expires or the job completes.
Sources: src/instrumentation.ts:57-61, CLAUDE.md:67-73
The following diagram illustrates the flow from schedule evaluation to job execution:
The diagram shows how the ticker enqueues jobs into the database and the processor periodically claims and executes them.
Sources: src/instrumentation.ts:70-124
Configurable Jobs
Several core features rely on this system. Administrators configure the schedules via the application settings UI.
| Job Name | Type | Purpose | Configuration Key |
|---|---|---|---|
REMINDER_CHECK | Scheduled | Checks for upcoming due dates and sends notifications. | reminder.cron |
BACKUP_RUN | Scheduled | Creates an encrypted SQLite snapshot and uploads it. | backup.cron |
EMAIL_INGEST | Scheduled | Checks IMAP mailboxes for document attachments. | emailIngest.cron |
PRICE_REFRESH | System | Updates equity and crypto prices from live feeds. | Hardcoded (15 min) |
OCR / Extraction | Ad-hoc | Processes uploaded documents for field extraction. | N/A (Triggered by upload) |
Sources: src/instrumentation.ts:80-101, CLAUDE.md:75-80, src/components/AppSettingsForms.tsx:355-365
External Triggering (API)
In addition to the internal node-cron ticker, the system exposes a REST endpoint for external schedulers. A POST request to /api/cron triggers the runPendingJobs() function directly.
Security
Access to the cron API is gated by the CRON_SECRET environment variable. Clients must provide this secret in the x-cron-secret header. If the environment variable is not set, the endpoint returns a 404 error.
The sequence diagram details the interaction between an external trigger and the internal job runner.
Sources: CLAUDE.md:120-125, src/instrumentation.ts:108-124
Implementation Details
The system defines specific behaviors to ensure reliability:
- Catch-up Reminders: If a record crosses several reminder thresholds at once (e.g., adding a contract already 20 days overdue), the system sends one catch-up notification per channel instead of multiple alerts.
- Encryption Dependencies: Database backups are disabled unless an
ENCRYPTION_KEYis configured. This key ensures that snapshots are encrypted using AES-256-GCM before offsite transmission. - Email Ingestion: The system polls configured IMAP mailboxes, identifies document types, and places them in the "Inbox" for manual review.
Sources: CLAUDE.md:79-80, src/instrumentation.ts:8-14, PRODUCT.md:28-30
The background job and cron system provides the automated backbone for Hearth's privacy-focused household management, ensuring that sensitive tasks like backups and reminders happen reliably according to user-defined schedules.