What Background Jobs Does the TREK Backend Run? A Complete Technical Guide

The TREK backend runs nine distinct background jobs using node-cron to handle database backups, cache maintenance, user notifications, and external data synchronization, all orchestrated from server/src/scheduler.ts.

The TREK travel planning application relies on a robust scheduling system to maintain data integrity and keep users informed without manual intervention. These background jobs in the TREK backend use the node-cron library to execute tasks on configurable intervals, with all definitions centralized in server/src/scheduler.ts. From creating ZIP backups to syncing flight data, each job targets specific maintenance needs to keep the system performant and up-to-date.

Overview of the Scheduling Architecture

All cron-based operations originate from server/src/scheduler.ts. This module exports a start() function that initializes enabled tasks based on persisted settings, and provides corresponding stop logic to cleanly halt each ScheduledTask during server shutdown.

The scheduler uses node-cron to create recurring tasks, with frequencies ranging from every few minutes to daily executions. Each job is designed to be idempotent and self-healing, logging activity through the audit system defined in server/src/services/auditLog.ts.

The Nine Background Jobs Explained

The TREK backend executes nine distinct scheduled tasks, each targeting specific maintenance or synchronization needs.

1. Automatic Database Backup and Retention

The automatic backup job creates a ZIP archive containing the SQLite database and all uploaded user files, storing the result in data/backups/. The frequency is configurable via user settings—options include hourly, daily, weekly, or monthly execution.

According to the source code in server/src/scheduler.ts (lines 61-90), the backup process reads the user's backup configuration to determine the schedule. A separate retention cleanup task (lines 101-115) purges archives older than the configured keep_days threshold, preventing unbounded disk usage.

2. Demo Mode User Reset

When DEMO_MODE=true, TREK runs a reset job every hour on the hour to maintain a pristine demonstration environment. This task invokes resetDemoUser() from server/src/demo/demo-reset.ts (referenced in scheduler.ts lines 46-55), wiping all demo-account data and restoring the default state for the next visitor.

3. Trip Start-Date Reminders

This notification job runs daily at 9:00 AM local time to alert users about upcoming trips. As implemented in server/src/scheduler.ts (lines 80-100), the job queries for trips whose start_date is exactly n days away, where n equals the user-defined reminder_days setting. It emits a trip_reminder notification through server/src/services/notificationService.ts.

4. Todo Due-Date Reminders

Running daily at 9:00 AM alongside trip reminders, this job monitors unchecked todo items. The implementation in server/src/scheduler.ts (lines 26-44) searches for todos whose due_date falls within the next 3 days (configurable via TODO_REMINDER_LEAD_DAYS). It sends a todo_due notification and records a timestamp to prevent duplicate alerts.

5. Version Update Checks

TREK checks for new releases daily at 9:00 AM by calling checkAndNotifyVersion() from server/src/services/adminService.ts. Scheduled in scheduler.ts (lines 78-92), this job queries the GitHub API to compare the running version against the latest release, emitting an admin notification if an update is available.

6. Idempotency Key Cleanup

To prevent the idempotency_keys table from growing indefinitely, a cleanup task runs every night at 3:00 AM. As defined in server/src/scheduler.ts (lines 94-112), this job deletes rows older than the configured TTL (defaulting to 30 days), ensuring API idempotency remains performant.

7. Trek-Photo Cache Maintenance

Cached trek photos are evicted every 2 hours plus once immediately on startup. The job calls sweepExpired() in server/src/services/memories/trekPhotoCache.ts (scheduled in scheduler.ts lines 140-152) to remove files and database rows that have exceeded the 1-hour TTL.

8. Place-Photo Cache Cleanup

Running nightly at 3:30 AM plus on startup, this task executes sweepOrphans() from server/src/services/placePhotoCache.ts (as scheduled in scheduler.ts lines 166-184). It deletes cached image files that are no longer referenced by any place or trip, reclaiming storage from stale downloads.

9. AirTrail Flight Synchronization

The AirTrail integration syncs flight data every 5 minutes by default, configurable via airtrail_poll_interval_minutes. The job invokes runAirtrailSync() from server/src/services/airtrail/airtrailSync.ts (scheduled in scheduler.ts lines 188-202), pulling updates from the AirTrail service and reconciling them with the local database to maintain bidirectional sync.

Key Implementation Files

Understanding the file structure helps when debugging or extending the scheduler:

• server/src/scheduler.ts — Central registry where all cron jobs are defined, started, and stopped.
• server/src/services/notificationService.ts — Handles trip_reminder and todo_due dispatching.
• server/src/services/adminService.ts — Implements checkAndNotifyVersion for release monitoring.
• server/src/services/memories/trekPhotoCache.ts — Provides sweepExpired for trek-photo eviction.
• server/src/services/placePhotoCache.ts — Provides sweepOrphans for place-photo cleanup.
• server/src/services/airtrail/airtrailSync.ts — Contains runAirtrailSync logic for flight data.
• server/src/demo/demo-reset.ts — Houses resetDemoUser for demo environment maintenance.
• server/src/services/auditLog.ts — Logs informational and error messages from all jobs.

Practical Code Examples

Enabling Automatic Backups

Configure the backup schedule programmatically by interacting with the scheduler settings:

import { loadSettings, saveSettings } from './scheduler';

// Enable daily backups at 02:00 AM with 7-day retention
const settings = loadSettings();
settings.enabled = true;
settings.interval = 'daily';
settings.hour = 2;
settings.keep_days = 7;
saveSettings(settings);

Manually Triggering a Cache Sweep

Force immediate eviction of stale trek-photo cache entries during troubleshooting:

import { sweepExpired } from './services/memories/trekPhotoCache';

// Forces immediate cleanup of expired entries
sweepExpired();

Checking AirTrail Sync Configuration

Verify or restart the AirTrail synchronization poller:

import { startAirTrailSync } from './scheduler';

// Reads airtrail_poll_interval_minutes and starts the poller
startAirTrailSync();

Summary

• Nine background jobs run continuously in the TREK backend, managed by node-cron from server/src/scheduler.ts.
• Database maintenance includes configurable backups with retention policies and idempotency key cleanup.
• User notifications for trips and todos dispatch daily at 9:00 AM using personalized lead-time settings.
• Cache management covers both trek-photo eviction (every 2 hours) and place-photo orphan removal (nightly).
• External sync with AirTrail occurs every 5 minutes by default, keeping flight data current.
• Demo mode automatically resets hourly when enabled, ensuring a consistent demonstration state.

Frequently Asked Questions

How does the TREK backend schedule background jobs?

The TREK backend uses the node-cron library to create ScheduledTask instances. All jobs are defined and started from the exported start() function in server/src/scheduler.ts, which reads configuration settings and launches the appropriate cron patterns. When the server shuts down, the scheduler cleanly halts each active task to prevent orphaned processes.

Can I customize the frequency of automatic database backups?

Yes. The automatic backup job supports configurable intervals including hourly, daily, weekly, or monthly execution. Users can set the interval, specific hour, and retention period (in days) through the application settings. The scheduler reads these values from the persisted configuration in server/src/scheduler.ts to determine when to trigger the next backup archive creation.

What prevents duplicate todo reminder notifications?

The todo reminder job implements a timestamp-tracking mechanism. When it sends a todo_due notification for an item due within the configured TODO_REMINDER_LEAD_DAYS, it records the reminder timestamp in the database. Subsequent runs check this timestamp to ensure notifications are not sent repeatedly for the same todo item, effectively preventing spam while keeping users informed of approaching deadlines.

How are background jobs stopped when the TREK server shuts down?

The server/src/scheduler.ts module exports stop logic that cleanly halts each running ScheduledTask instance. When the server receives a shutdown signal, it invokes this stop function to destroy all cron jobs gracefully, ensuring that no partial operations remain in flight and that the SQLite database connections close properly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}