gao.ninja logogao.ninja

Timezone Hell in Recurring Bookings

A few years ago I worked on a healthcare product that started simple: one hospital, a small ops team, and a very human recurring-booking "system". Patients in ongoing treatment wanted a standing appointment every week or every two weeks without re-booking each time, and a real person handled the schedule changes, follow-ups and reminders. That worked fine.

Then we raised money. "One hospital" became "one hospital plus a few new clinics", the manual approach stopped scaling, and we needed a recurring booking feature that could run reliably without creating chaos for staff or patients. So we built it, and like many teams before us, we told ourselves: "Just store everything in UTC."

It worked, until it didn't.

The part that worked (for a while)

The first implementation was clean and comforting. We normalized every timestamp to UTC, stored a single point in time for each occurrence, rendered it in whatever timezone the client device reported, and sent reminders based on server time.

For one-off appointments, that approach is usually fine. A timestamp like 2026-02-22T15:00:00Z is a specific moment, and everyone can agree on it. The problem is recurrence, because a recurring appointment is not a moment in time. It's intent. "Every Wednesday at 3pm" is not the same thing as "every 604800 seconds", and the gap between those two ideas is exactly where we fell in.

Where it blew up: DST

We hadn't properly accounted for Daylight Saving Time. On the DST switch, the system could no longer reliably answer "which appointment is in one hour?" Some patients got reminders an hour early, others an hour late, and support couldn't tell whether the calendar was wrong, the patient was wrong, or the reminder service was wrong.

Then we found the extra twist: not all US states observe DST (Hawaii and most of Arizona don't). So in the same country, at the same time of year, our "simple UTC strategy" behaved differently depending on where the appointment happened.

That's the moment you realize: your UTC timestamp is correct, but your meaning is missing.

Two timelines for a weekly 3pm appointment in Los Angeles across the March DST change. Adding 7 times 24 hours to the UTC timestamp lands at 4pm local time, while adding one calendar week to the local time keeps it at 3pm and shifts the UTC time by an hourSame rule, two storage models: only one keeps the appointment at 3pm

A weekly 3pm appointment in Los Angeles sits at 23:00 UTC on standard time. When clocks spring forward, the rule stays the same ("Wednesday at 3pm"), but the correct UTC timestamp moves to 22:00. Keep adding a week of seconds to the stored UTC value and the appointment quietly drifts to 4pm on the clinic's wall clock.

The second trap: travel

Our first emergency fix was to make everything "timezone-aware" by attaching a timezone such as America/Los_Angeles. Offsets started changing when they should and times displayed more consistently, but one easy-to-miss edge case remained.

Patient: I booked my 3pm appointment in San Francisco. I'm in New York this week. When do I show up?

System: That depends on what you meant by "3pm", and I never asked.

"3pm" is not a point in time. It's a wall-clock value. It only becomes unambiguous once you attach a timezone, and often a location. If you treat "3pm" as "whatever timezone the user is in right now", you are implicitly using the viewer timezone (the phone or laptop timezone at render time) as the source of truth. That's fine for "show me the current time", but dangerous for scheduling. There are at least three different meanings in play:

"3pm" means…Which timezoneIf the patient travels SF → NY
3pm at the clinicEvent/location timezoneDisplay changes (6pm NY), the moment does not
3pm wherever I am nowViewer/device timezoneThe appointment moves relative to the clinic
3pm where I'll be that dayFuture intentValid for telehealth or travel planning, but you must ask

The weird outcomes happen when a system mixes these up. If you store a floating 15:00 and later render it in the user's current timezone, 3pm in San Francisco becomes 3pm in New York: the appointment drifts when the user moves. If the appointment is anchored to the clinic, 3pm in San Francisco correctly displays as 6pm in New York, the same moment shown in another zone. And if the user meant New York time but the system assumed San Francisco (or kept only UTC without the original timezone), 3pm in New York turns into 12pm in San Francisco, a completely different wall-clock time.

So conversion isn't the real problem. It's straightforward once you know which timezone the user meant. Without stored intent (time, IANA timezone, and what that timezone represents), the system is forced to guess, and it will guess wrong around travel and DST.

What we should have stored: time + timezone + intent

UTC is perfect for a point in time. Recurring appointments are rules: every Wednesday at 3pm, every two weeks on Friday at 09:30, the first business day of the month at 08:00. Those rules are anchored to a local calendar and a local timezone, both of which can change because of DST or policy changes. Store only UTC and you've lost the rule, so regenerating future occurrences means guessing, and eventually guessing wrong.

The fix isn't "store UTC" versus "store a timezone". It's store both, plus the intended scheduling timezone. A useful mental model: the UTC timestamp says when this occurrence happens in the universe, while local time plus IANA timezone says what the user meant on the calendar. "Wednesday at 3pm in San Francisco" is not a single string. It's a structure:

{
  "time": "2026-03-18T15:00:00",
  "tz": "America/Los_Angeles"
}

Notice what's missing: an offset like -08:00. Offsets change, but the IANA timezone name captures the rules over time.

For healthcare there's a practical shortcut, because most appointments are physical and the patient has to show up at the clinic. The clinic exists in one location, staff schedules run on that location's time, and the patient needs to be there at the clinic's wall-clock time. So anchor the appointment to the clinic's timezone, not the patient's current device timezone. Even if the patient travels, the appointment stays "3pm at the clinic", and only the display adapts to the viewer. We also made this explicit in the UI by showing the clinic timezone next to the appointment time, and in confirmations and reminders. It reduced confusion immediately, because patients could see what the system considered the source of truth.

Recurrence math is where it gets truly weird

Even with the right data stored, recurrence can still bite you. A week isn't always 7 × 24 hours in a given timezone: across a DST change it can be 167 or 169 hours. Naively computing "UTC timestamp + 1 week" shifts local times by an hour at every DST boundary. The safer approach is:

  1. Interpret the stored local time + timezone as a zoned datetime.
  2. Add one week in the calendar sense, not in seconds.
  3. Convert the resulting zoned datetime to UTC for storage and notifications.

With Luxon, for example, that looks like this:

import { DateTime } from "luxon";

const first = DateTime.fromISO("2026-03-04T15:00:00", {
  zone: "America/Los_Angeles",
});

const next = first.plus({ weeks: 1 }); // 2026-03-11T15:00 local, after DST
const nextUtc = next.toUTC().toISO(); // 22:00Z, not 23:00Z

Libraries like date-fns-tz, Luxon or Joda-Time exist for a reason. A hand-rolled solution will eventually become a bug farm.

You can't fix what you didn't record

The hardest part of our incident wasn't changing code. It was data. We hadn't stored enough intent to confidently migrate existing schedules. When an appointment is off by an hour, you can't always tell whether the user wanted 3pm clinic time no matter what, 3pm in their current timezone, or 3pm wherever they'd be that day. If you didn't record the intent, you can't reconstruct it later without asking users, and that's rarely feasible in production.

Watch out: A data-model gap in scheduling is not something you can patch later with code. Decide what each stored time means before the first booking is saved.

If I'm building scheduling again, especially recurring scheduling, this is the checklist I start with:

  • Store local time without an offset (e.g. 2026-03-18T15:00:00).
  • Store the IANA timezone (e.g. America/Los_Angeles).
  • Store who or what the timezone belongs to: clinic, provider, patient or resource.
  • Store UTC for each generated occurrence, for notifications, ordering and queries.
  • Do recurrence math in the target timezone, not in UTC seconds.
  • Be explicit in the UI: "This appointment is scheduled in Clinic time (America/Los_Angeles)".

Wrapping up

UTC is necessary, but it is not sufficient. Use UTC for moments and time + timezone for intent, and record which party that timezone belongs to. If you're doing recurrence, assume you're already in timezone hell and design your data model so you can survive it, because the day you hit DST in production is not the day you want to learn how time works.