Timezone-Aware Scheduling — Building Reliable Schedulers

Timezone-Aware Scheduling

Building a reliable scheduling system requires careful timezone handling. A meeting at "10:00 AM New York time" needs to work correctly whether New York is in EST or EDT.

The Core Problem

Consider a recurring meeting: "Every Monday at 10:00 AM Eastern Time"

In winter (EST): 10:00 AM = 15:00 UTC
In summer (EDT): 10:00 AM = 14:00 UTC

If you store this as "15:00 UTC every Monday," the meeting will be at 11:00 AM local time during summer. Instead, store it as:

{
  "recurrence": "FREQ=WEEKLY;BYDAY=MO",
  "localTime": "10:00",
  "timezone": "America/New_York"
}

One-Time Events vs Recurring Events

One-time events should be stored as UTC:

{
  "type": "one-time",
  "startsAt": "2024-03-15T14:30:00Z"
}

Recurring events should store local time + timezone:

{
  "type": "recurring",
  "localTime": "10:30",
  "timezone": "America/New_York",
  "recurrence": "FREQ=DAILY"
}

DST Transition Handling

When a recurring event falls during a DST transition:

Spring Forward (gap): If the event is at 2:30 AM and clocks skip from 2:00 AM to 3:00 AM:

• Option A: Run at 3:00 AM (first valid time after the gap) — most common
• Option B: Skip the occurrence — safest

Fall Back (overlap): If the event is at 1:30 AM and clocks repeat 1:00-2:00 AM:

• Option A: Run on the first occurrence (before fallback) — most common
• Option B: Run on the second occurrence (after fallback)
• Option C: Run twice — rarely desired

Cron Jobs and Timezones

Most cron implementations run in the server's timezone. To schedule a job at 10 AM New York time from a UTC server:

# This doesn't work — cron uses server time
0 10 * * * /path/to/script  # 10 AM UTC, not New York!

# Solution 1: Use TZ environment variable (Linux)
TZ="America/New_York" 0 10 * * * /path/to/script

# Solution 2: Use a timezone-aware scheduler (AWS EventBridge, etc.)

Cross-Timezone Coordination

For events involving multiple timezones, store the "anchor" timezone and compute others:

// Meeting anchored to New York 10 AM
const anchor = { time: "10:00", timezone: "America/New_York" };

// Show to London participant
// In winter: 3:00 PM GMT
// In summer: 3:00 PM BST (because both shifted by 1 hour)
// Note: This isn't always true — US and EU switch on different dates!