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

> Discover the nine background jobs the TREK backend runs for backups, cache, notifications, and data sync. Explore the scheduler for a complete technical guide.

- Repository: [Maurice/TREK](https://github.com/mauriceboe/TREK)
- Tags: deep-dive
- Published: 2026-07-03

---

**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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/server/src/demo/demo-reset.ts) (referenced in [`scheduler.ts`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/server/src/services/adminService.ts). Scheduled in [`scheduler.ts`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/server/src/services/memories/trekPhotoCache.ts) (scheduled in [`scheduler.ts`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/server/src/services/placePhotoCache.ts) (as scheduled in [`scheduler.ts`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/server/src/services/airtrail/airtrailSync.ts) (scheduled in [`scheduler.ts`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/server/src/scheduler.ts)** — Central registry where all cron jobs are defined, started, and stopped.
- **[`server/src/services/notificationService.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/services/notificationService.ts)** — Handles `trip_reminder` and `todo_due` dispatching.
- **[`server/src/services/adminService.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/services/adminService.ts)** — Implements `checkAndNotifyVersion` for release monitoring.
- **[`server/src/services/memories/trekPhotoCache.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/services/memories/trekPhotoCache.ts)** — Provides `sweepExpired` for trek-photo eviction.
- **[`server/src/services/placePhotoCache.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/services/placePhotoCache.ts)** — Provides `sweepOrphans` for place-photo cleanup.
- **[`server/src/services/airtrail/airtrailSync.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/services/airtrail/airtrailSync.ts)** — Contains `runAirtrailSync` logic for flight data.
- **[`server/src/demo/demo-reset.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/demo/demo-reset.ts)** — Houses `resetDemoUser` for demo environment maintenance.
- **[`server/src/services/auditLog.ts`](https://github.com/mauriceboe/TREK/blob/main/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:

```typescript
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:

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

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

```

### Checking AirTrail Sync Configuration

Verify or restart the AirTrail synchronization poller:

```typescript
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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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.