Design Google Calendar: Recurring Events, Time Zones, Free/Busy and Sync

One weekly meeting, from 'Save' to a reminder on a guest's phone

Ana, in New York, creates a weekly Monday 9:00 meeting and invites Ben and Chen. Follow it through the system. This is a good order to explain it in an interview.

1. 1

   Saved

   The event service writes one event row on Ana's shard: title, guests, start 2026-10-19 09:00 in America/New_York, and the rule FREQ=WEEKLY;BYDAY=MO. In that transaction it writes an outbox row and a line in Ana's change log. Ana gets 'saved' back.

2. 2

   Fanned out

   A fan-out worker reads the outbox row. It writes a calendar entry for Ben on Ben's shard and one for Chen on Chen's shard. Each entry has the event id, a copy of the title and times, and the guest's answer, set to 'needs action'. Each write also appends a line to that guest calendar's change log.

3. 3

   Expanded

   The worker turns the rule into real dates for the next 12 months: 52 Mondays, each converted from 9:00 New York time to UTC. These rows go into the instance index on each of the three calendars' shards.

4. 4

   Reminders planned

   The reminder planner sees new instances starting in the next day and adds jobs to the delayed-job scheduler, for example 'tell Ben at 08:50 New York time on Monday'. Later Mondays are planned as they come closer.

5. 5

   Phones told

   The push service tells Ben's devices that his calendar changed. The message carries no event data. Each device asks for changes since its sync token, gets the new event, and saves the new token.

6. 6

   Answered

   Ben taps yes. His answer is sent to the event on Ana's shard, then fanned out again, so Ana and Chen see that Ben is coming.

7. 7

   Reminded

   At 08:50 on Monday the job comes due. The worker checks that the event still exists and has not moved, then the notification service sends Ben a phone notification.

These are the conversations the interviewer is steering you toward. Practice each one until you can talk through it without notes.

Recurring events: a rule plus exceptions, materialized rows, or both

A repeating meeting can be stored in two ways. The first way stores the rule. iCalendar (RFC 5545) is the open standard most calendar apps share, and it describes a series with a start time (DTSTART) and a rule (RRULE), such as FREQ=WEEKLY;BYDAY=MO for every Monday. The standard says the start time always counts as the first occurrence. A series ends with COUNT (a number of times) or UNTIL (a last date), never both, and with neither it repeats forever. A cancelled date is listed in EXDATE. A date that was changed is stored as a separate override, identified by RECURRENCE-ID: the original start time that the rule produced for it. Google's API works this way too. Its recurrence field holds RRULE, EXRULE, RDATE and EXDATE lines, and each instance carries recurringEventId (the series it belongs to) and originalStartTime, which Google says identifies the instance even if it was moved. The second way is to materialize: write one row per date. Reads become simple range scans, but a series with no end date cannot be written out, and changing the series means rewriting every row. The answer most designs reach is a hybrid. The rule and its overrides are the truth. A rolling window of expanded rows, say the next 12 months, is kept as an index for the things that need fast lookups by time: free/busy, conflict checks and reminders. Anything outside the window, such as 'show me March 2029', is expanded when someone asks. Edits come in three kinds. 'This event only' adds an override. 'All events' changes the rule and rebuilds the window. 'This and following events' is usually done by splitting the series: the old series gets an UNTIL just before the chosen date, and a new series starts on that date. iCalendar also has RANGE=THISANDFUTURE for this, but a split keeps each series simple. One trap: when a rule changes, old overrides may no longer match any date the new rule produces. Decide up front whether to drop them or keep them, and tell the user. Another trap: a moved date can move into the window you asked for from outside it, so a range read must also check overrides whose new time falls inside the window.

from datetime import datetime, timezone
from zoneinfo import ZoneInfo
from dateutil.rrule import rrulestr

NY = ZoneInfo("America/New_York")
start = datetime(2026, 10, 19, 9, 0, tzinfo=NY)        # first Monday, 9:00 in New York
rule = rrulestr("FREQ=WEEKLY;BYDAY=MO", dtstart=start)  # the stored rule
exdates = {datetime(2026, 11, 9, 9, 0, tzinfo=NY)}      # one Monday cancelled
moved = {datetime(2026, 10, 26, 9, 0, tzinfo=NY):       # one Monday moved to 11:00
         datetime(2026, 10, 26, 11, 0, tzinfo=NY)}

lo = datetime(2026, 10, 19, tzinfo=timezone.utc)        # the window asked for
hi = datetime(2026, 11, 17, tzinfo=timezone.utc)
for t in rule.between(lo, hi, inc=True):
    if t in exdates:
        continue
    t = moved.get(t, t)
    print(t.strftime("%b %d %H:%M %Z"), "=", t.astimezone(timezone.utc).strftime("%H:%M UTC"))

# Oct 19 09:00 EDT = 13:00 UTC
# Oct 26 11:00 EDT = 15:00 UTC
# Nov 02 09:00 EST = 14:00 UTC
# Nov 16 09:00 EST = 14:00 UTC

Time zones and daylight saving: why UTC alone breaks repeating meetings

UTC (Coordinated Universal Time) is the world's reference clock. It never jumps forward or back. Storing a single meeting in UTC is fine, because that meeting happens at one moment. A repeating meeting is different, because people agree on a local time: 9:00 every Monday in New York. Daylight saving time (DST), also called summer time, moves local clocks by an hour twice a year, so 9:00 in New York is 13:00 UTC in summer and 14:00 UTC in winter. New York's summer time is called EDT (UTC minus 4 hours) and its winter time EST (UTC minus 5 hours). In 2026, US clocks go back on Sunday November 1. If you store the series as '13:00 UTC every Monday', the meeting shows at 8:00 in New York from November 2. So the rule must be stored as a local time plus a time zone name, such as America/New_York, and turned into UTC date by date. RFC 5545 does this with DTSTART;TZID=America/New_York, and its own example of a daily 9:00 meeting reads 9:00 AM EDT in October and 9:00 AM EST from October 26, 1997. Google's API puts it in plain words: for recurring events the time zone is required, and it is the zone in which the recurrence is expanded. Use the organizer's zone, because the meeting belongs to the organizer's working day. Guests in other countries will see it move. A London guest of the New York meeting sees 14:00, then 13:00 for one week (the UK changes its clocks on October 25, 2026, a week before the US), then 14:00 again. That is correct behaviour, and your interviewer may ask about it. Three more details matter. First, some local times do not exist: on the night clocks jump forward, 2:30 AM never happens. RFC 5545 says a recurrence instance that falls on a nonexistent local time, or on an impossible date such as February 30, must be ignored and not counted. Second, the rules change. The IANA tz database, the public list of every region's offsets and clock changes, has no fixed release schedule and usually publishes a new release every few months, and governments sometimes change their rules with little notice. When new tz data arrives, rebuild the instance index and the reminder jobs for the affected zones. Third, all-day events, like a birthday, have no time zone at all. They are a date, and must stay on that date wherever the viewer is.

Free/busy queries and conflict detection

A free/busy query asks: when is each of these people busy between two times? Google's API has this as one call, freebusy.query. It takes timeMin, timeMax and a list of calendars, and returns, for each calendar, a list of busy periods with a start and an end. Only times are returned, never titles. The call can expand a group into its members, up to 100 (groupExpansionMax), and look up at most 50 calendars (calendarExpansionMax). iCalendar has a matching component, VFREEBUSY. The server answers it from the instance index. For each calendar it reads the instances in the range that count as busy: the event blocks time (Google's transparency field is opaque, shown as Busy), the event is not cancelled, and the person has not declined. Each calendar is one range read on one shard (a read of the rows between two keys, here two times), so 8 people means 8 reads in parallel. To find a slot for everyone, put all the busy periods in one list, sort them by start, and join any that touch or overlap. The gaps between the joined blocks, inside working hours, are the free slots. Sorting a few hundred periods takes almost no time. Conflict detection uses the index too. Two periods overlap when each one starts before the other ends: a.start < b.end and b.start < a.end. For a person, a clash is only a warning, because people do double-book on purpose. A meeting room is different: it must never be booked twice. Treat each room as a calendar of its own and do the check and the insert in one transaction on the room's shard, locking the room's row first. Two people trying to book one room at one moment are then served one after the other, and the second one sees the clash.

def merge(busy):                      # busy: list of (start, end) in minutes
    out = []
    for s, e in sorted(busy):
        if out and s <= out[-1][1]:   # touches or overlaps the last block
            out[-1][1] = max(out[-1][1], e)
        else:
            out.append([s, e])
    return out

def free_slots(busy, day_start, day_end, need):
    slots, t = [], day_start
    for s, e in merge(busy):
        if s - t >= need:
            slots.append((t, s))
        t = max(t, e)
    if day_end - t >= need:
        slots.append((t, day_end))
    return slots

ana  = [(540, 600), (660, 720)]       # 9:00-10:00, 11:00-12:00
ben  = [(570, 630), (780, 840)]       # 9:30-10:30, 13:00-14:00
chen = [(720, 750)]                   # 12:00-12:30
print(free_slots(ana + ben + chen, 540, 1020, 30))
# [(630, 660), (750, 780), (840, 1020)]  -> 10:30-11:00, 12:30-13:00, 14:00-17:00

Invitations and attendee fan-out: one event, many calendars

When Ana invites Ben, the meeting has to appear on Ben's calendar. Google's guide says that an event you create appears on the primary calendars of all the guests you included, with one event ID shared by every copy. There are two ways to build that. One way gives each guest a full, separate copy. Reads are easy, but copies drift apart, and every edit must rewrite every copy in full. The other way keeps one event on the organizer's shard and gives each guest a small calendar entry that points to it. The entry holds what is personal to the guest: their answer, their reminders, their colour. To keep a week view fast, it also holds a copy of the title and times. That copy is a cache, refreshed on every change. The change is spread by fan-out: the event service writes the event and an outbox row in one transaction, and workers then update each guest's entry and change log. Fan-out is asynchronous, which means it runs after Ana's request has returned. So Ben may see the change a second or two later, which is fine for a calendar. Every fan-out write carries the event's version number, and an entry only accepts a newer version. A retried message or two changes that arrive out of order then cannot leave Ben with an old title. Answers travel the other way: Ben's 'yes' updates the attendee row on Ana's shard, which bumps the version and fans out again, so Chen sees Ben's answer too. iCalendar has a field for this called SEQUENCE: the organizer increases it on each significant change, and an answer names the sequence it refers to, so an answer to an old version can be spotted. Guests outside the system, such as a person on another email provider, get an email invitation instead of an entry. Google's API sends these when sendUpdates is set to all or externalOnly. Big meetings need care. A company meeting with 10,000 guests is 10,000 entry writes for every edit. Send them through a queue with a rate limit, so one big meeting fills its own lane and does not delay everyone else's small ones. That is back-pressure: the system slows the producer down when consumers fall behind. Google also caps abuse: its Workspace limits say a user who sends about 10,000 invitations to people outside their domain in a short period gets throttled.

Reminders at scale: a delayed-job scheduler

A reminder is a job that must run at a set time in the future: 'tell Ben at 08:50'. Google lets each event override the calendar's default reminders with up to 5 of its own, from 0 to 40,320 minutes (4 weeks) before the start, sent as a popup or an email. Reminders are personal, so they belong to the guest's entry, not to the event. A system with 400 million reminders a day cannot scan every event every minute. It needs a delayed-job scheduler, the pattern in the site's distributed job scheduler guide. A planner turns upcoming instances into jobs, but only for a short horizon such as the next 24 hours. Planning a year ahead would mean replanning a year of jobs every time a series changes. A sweep job runs every hour and plans the next slice. Each job goes into a time bucket keyed by the UTC minute it fires and by a bucket number from 0 to N, so the 08:50 rush is spread over N partitions and N workers. Reminders bunch hard on the hour and half hour: in our estimate the busiest minute runs at about 133,000 a second against an average of 4,600, so the scheduler is sized for that minute. When a minute arrives, workers claim its buckets, and each claimed job is checked before anything is sent. Does the event still exist? Is the version unchanged since the job was planned? Did Ben decline? If anything changed, the job is dropped and the planner makes a fresh one. This check at fire time is much simpler than hunting down and deleting every old job each time an event moves. Jobs may run twice after a worker crash, so the send is made idempotent with a key such as (calendar, event, original start, minutes before), and the notification service skips a key it has already sent. The course lesson on the Delayed Queue pattern teaches this structure on its own.

WITH due AS (
  SELECT job_id
  FROM reminder_jobs
  WHERE bucket = $1
    AND fire_minute_utc <= now()
    AND state = 'planned'
  ORDER BY fire_minute_utc
  LIMIT 500
  FOR UPDATE SKIP LOCKED
)
UPDATE reminder_jobs r
SET state = 'claimed', claimed_at = now()
FROM due
WHERE r.job_id = due.job_id
RETURNING r.job_id, r.calendar_id, r.event_id,
          r.original_start, r.event_version;

Incremental sync: change logs and sync tokens

A phone keeps a copy of the calendar so it works offline. The question is how it learns what changed without downloading everything again. Google's answer is the sync token. The first time, the phone lists everything and gets a nextSyncToken on the last page. Next time it sends that token and gets only the events changed since then. Google's guide says the result always includes deleted entries, so the phone can remove them too. If the token has expired, the server answers 410 Gone, and the phone must wipe its copy and do a full sync. The server side of this is a change log per calendar. Every change to a calendar appends a line with a sequence number one higher than the last, inside the transaction that makes the change. A sync token is an encoded (calendar id, sequence number). 'Changes after 41' is one range read on one shard, ordered by sequence, a page at a time. Only the newest line per event needs to be sent, and a deleted event is sent as a tombstone: a marker that says 'this event is gone'. The log cannot grow forever, so lines older than some weeks are trimmed, and a token older than the trim point gets 410. A token also has to stay meaningful. That is why Google does not let a sync request add filters such as timeMin, timeMax or a search query: a token that meant 'all changes after 41' cannot quietly start to mean 'some changes'. Polling 20 times a day per device is wasteful, so there are push channels as well. In Google's API, a watch request registers a web address, and a POST (a web request that carries data to that address) is sent to it when the calendar changes. The message has no body and no details; the receiver must call sync to learn what changed. Channels expire (the default lifetime is 604,800 seconds, 7 days) and must be renewed. Google also warns that notifications are not 100% reliable and a small share is dropped. So a good client does both: sync when pushed, and sync on a slow timer anyway.

SELECT DISTINCT ON (event_id) event_id, seq, kind
FROM change_log
WHERE calendar_id = $1
  AND seq > $2            -- the sequence number inside the sync token
  AND seq <= $3           -- upper bound fixed on the first page
ORDER BY event_id, seq DESC;
-- new token = (calendar_id, $3); if $2 is older than the trim point: 410 Gone

Sharding, hot calendars and huge meetings

Sharding means splitting the data across many machines, each holding a slice. The shard key is the value that decides which slice a row goes to. Here the key is the calendar id. Everything about one calendar sits together: its entries, its change log and its instance index. The most common reads, 'show my week' and 'what changed on my calendar?', then touch one shard. Hash the calendar id with consistent hashing, a way of mapping keys to machines so that adding a machine moves only a small share of keys. The event row itself lives on the organizer's calendar shard, which is why a change to Ana's meeting starts on Ana's shard and fans out to the others. Free/busy for 8 people is 8 shards read in parallel, which is fine at that size, and it is one reason Google caps a free/busy call at 50 calendars. Two shapes break the simple plan. The first is a calendar with a very large number of readers, such as a company holiday calendar that every employee subscribes to. Copying each holiday into every subscriber's entries would turn one edit into a huge number of writes. So a subscribed calendar is read in place: the client merges it into the view, and a cache in front of its shard serves the many reads. Social feeds face a similar choice for accounts with millions of followers. The second is a meeting with thousands of guests, handled by a rate-limited fan-out lane as described in the invitations section. Also watch for skew in time: on a Monday morning, every time zone's working day starts within a few hours, so reads and writes surge together. Size for the 3 times peak, and keep the expensive work, fan-out and expansion, in queues that can fall a little behind without anyone losing data.

How Google Calendar actually does it

Google has not published how Calendar stores data inside, so this page designs a system that behaves like Google Calendar's public API, and names each place the API shows the idea. Recurring events: the API stores RRULE, EXRULE, RDATE and EXDATE lines from RFC 5545, requires a time zone for a recurring event and expands the rule in it, and identifies each instance by recurringEventId and originalStartTime. events.list returns the series and its exceptions, and singleEvents=true expands them into instances instead. Guests: an event appears on the primary calendars of all its guests with one shared event ID, answers are needsAction, accepted, declined or tentative, and sendUpdates controls the email to guests. Reminders: up to 5 per event, 0 to 40,320 minutes ahead, by popup or email. Free/busy: freebusy.query returns only busy periods and caps groups at 100 members and calls at 50 calendars. Sync: a nextSyncToken on the last page, deleted entries always included, a restricted set of filters, and 410 for an expired token. Push: watch channels with empty messages, a default lifetime of 7 days, and a warning that some messages are dropped. Limits: the API allows 10,000 requests per minute per project and 600 per minute per user per project, and Google Workspace throttles a user after about 10,000 invitations to outside guests or more than 100,000 new events in a short period. The open standards describe these ideas in their own terms. RFC 5545 defines RRULE, EXDATE, RECURRENCE-ID, SEQUENCE and VFREEBUSY, and its examples use America/New_York to show a 9:00 meeting moving from EDT to EST. RFC 4791, CalDAV, says that all parts of a series with one UID (the event's unique id) must be stored in one calendar object, and gives clients a choice: ask the server to expand a series into instances for a time range, or receive the series and its overrides. The IANA tz database holds the history of every region's offsets and clock changes and ships a new release every few months.

Frequently asked questions