Background Cron Scheduler

Relevant source files

The following files were used as context for generating this wiki page:

• app/api/cron/tick/route.ts
• lib/cron/scan.ts
• lib/cron/authorize.ts
• lib/cron/lease.ts
• README.md
• lib/db/schema.ts

The Background Cron Scheduler manages recurring data collection and pipeline processing tasks for the Vantage platform. It executes every three hours to poll all registered sources, normalize collected content, and generate leads based on the intent ladder.

Sources: README.md:38-38, README.md:104-106

Architecture Overview

The scheduler operates as a Vercel/Cloudflare cron job that targets a specific API endpoint. When the scheduled time arrives, the worker-entry handler invokes the tick route using a service binding.

The diagram shows the trigger flow from the external cron service through the internal authorization layer to the scanning logic.
Sources: README.md:107-112, app/api/cron/tick/route.ts

Security and Authorization

The system protects the cron endpoint from unauthorized external access. It requires an Authorization header containing a Bearer token that matches the CRON_SECRET environment variable.

• Token Verification: The authorizeCronRequest function compares the request header against the stored secret.
• Constant-Time Check: The system uses secure comparison to prevent timing attacks.
• Worker Self-Reference: Cloudflare Workers use a WORKER_SELF_REFERENCE service binding to reach the tick route internally.

Sources: lib/cron/authorize.ts, README.md:107-112

Lifecycle and Leasing

To prevent multiple instances of the cron job from running concurrently, the scheduler implements a leasing mechanism. This ensures that only one worker processes a specific workspace at any given time.

Lease Mechanics

When a scan starts for a workspace, the system attempts to acquire a lease. If a lease is already active and has not expired, the scheduler skips that workspace to avoid collisions.

The sequence diagram illustrates the atomic update process used to secure a workspace for processing.
Sources: lib/cron/lease.ts, lib/db/schema.ts:89-90

Database Schema for Leases

The workspace table maintains fields specifically for managing these background tasks:

Field	Type	Purpose
scanLeaseToken	text	A unique identifier for the current active scan.
scanLeaseUntil	timestamp	The expiration time for the current lease.

Sources: lib/db/schema.ts:89-90

Scanning and Pipeline Execution

The core logic resides in lib/cron/scan.ts. This module coordinates the discovery and processing of new data across all tenants.

1. Workspace Discovery: Queries all active workspaces requiring updates.
2. Source Polling: Iterates through every source (HN, RSS, Substack, Reddit, etc.) associated with the workspace.
3. Pipeline Run: Triggers the normalization and intent-scoring pipeline to convert raw documents into lead records.

Sources: lib/cron/scan.ts, README.md:31-38

Configuration and Deployment

The scheduler configuration is defined in the project deployment settings and environment variables.

Variable	Description	Location
CRON_SECRET	32+ random bytes used for API authorization.	Wrangler Secrets
cron schedule	Set to 0 */3 * * * (Every 3 hours UTC).	wrangler.jsonc (staging)

Sources: README.md:88-88, README.md:104-106

The scheduler ensures high technical accuracy by reusing the single deployed bundle and authorization logic, rather than duplicating the pipeline into a separate entry point.
Sources: README.md:107-112