Design a Calendar

Ana in New York books a weekly Monday 9:00 meeting with Ben in London and Chen in Singapore. It reaches their phones within seconds at the right local time, reminds them ten minutes before, and stays at 9:00 for Ana after the clocks change in March. The shared calendar in the big office suites is the kind of product this question means.

Interviewers like it because the boxes are ordinary and the data is not: "every Monday, forever" cannot be stored as rows, local time is not UTC, and "when are these eight people free?" touches eight shards. The steps follow A Framework for Any Design. Try each "Your turn" box before you read on.

#Clarify the problem

• Functional: create, edit and delete events; invite people and record replies; repeating events with per-occurrence changes; day, week and month views; free/busy for many people; reminders; sync to every device.
• Non-functional: saved events are durable and read-your-writes for their owner; attendees see changes within about 5 seconds; a week view loads in under 200 ms; reminders arrive within 60 seconds of their time and are never skipped; correct local times across time zones and daylight saving.
• Out of scope: other providers, video calls, room rules beyond "a room has a calendar".

#Estimate the scale

These are this scenario's assumptions, not any real product's. A day has 86,400 seconds; assume peaks of 3 times the average.

• Writes: about 2 a day per active user (creates, edits, replies): 100 million a day ÷ 86,400 ≈ 1,200 a second, 3,500 at peak.
• Reads: about 20 views or syncs a day per active user: 1 billion ÷ 86,400 ≈ 12,000 a second, 35,000 at peak. Reads outnumber writes 10 to 1.
• Free/busy: if half of the 50 million events created daily use the scheduling view, that is 25 million ÷ 86,400 ≈ 290 lookups a second, 870 at peak; at about 5 people each, 4,300 per-person lookups a second at peak.
• Reminders: 50 million users × 4 meetings = 200 million reminders a day, about 2,300 a second on average.

#Define the API

POST /calendars/{cal}/events            Idempotency-Key: 7f3a...
  body: { "title": "Team sync",
          "start": { "local": "2027-03-01T09:00", "tz": "America/New_York" },
          "duration_min": 30,
          "rrule": "FREQ=WEEKLY;BYDAY=MO",          optional
          "attendees": ["ben@...", "chen@..."],
          "reminders": [{ "before_min": 10, "via": "push" }] }
  201 { "event_id": "e81", "version": 1 }
 
GET /calendars/{cal}/events?from=2027-03-01&to=2027-04-01&tz=Europe/London
  200 { "occurrences": [ { "event_id": "e81", "original_start": "...",
                           "start": "...", "end": "...", "title": "..." } ] }
  400 window longer than 1 year
 
PATCH /events/{id}?scope=this|following|all&occurrence=2027-03-22T09:00
  If-Match: 4
  200 { "version": 5 }
  412 Precondition Failed   someone else changed it; body has the current event
 
POST /events/{id}/reply      { "response": "accepted", "occurrence": ...? }
POST /freebusy               { "people": [...], "from": ..., "to": ... }
  200 { "busy": { "ben@...": [ ["2027-03-01T14:00Z", "2027-03-01T14:30Z"] ] } }
GET  /calendars/{cal}/changes?since=token
  200 { "changes": [...], "next": "token" }
  410 Gone   token too old; do a full resync

The decision worth arguing is who expands repeating events. The view endpoint expands on the server, so a web page gets plain occurrences. The sync endpoint sends the raw rule and exceptions, so a phone can expand any month offline. Both must use the same expansion library, or phone and web will disagree on edge cases.

#Model the data

events                       -- on the organizer's shard
  event_id      BIGINT PRIMARY KEY
  organizer     BIGINT
  title, description, location   TEXT
  start_local   TIMESTAMP        -- 2027-03-01 09:00, no zone attached
  tz            VARCHAR(40)      -- "America/New_York"
  duration_min  INT
  rrule         TEXT NULL        -- "FREQ=WEEKLY;BYDAY=MO"
  version       INT
 
exceptions                   -- one row per changed occurrence
  event_id, original_start       PRIMARY KEY
  cancelled     BOOLEAN
  new_start_local, new_duration, new_title   NULL = unchanged
 
entries                      -- one per attendee, on THEIR shard
  calendar_id, event_id          PRIMARY KEY
  span_start_utc, span_end_utc   -- span_end = 9999-12-31 if no end
  start_local, tz, duration_min, rrule, title   -- copied from the event
  exceptions    JSON             -- copied, plus this person's own declines
  response      VARCHAR(10)      -- needs-action | accepted | declined
  reminders     JSON
  INDEX (calendar_id, span_end_utc)
 
changes                      -- per calendar, for device sync
  calendar_id, seq               PRIMARY KEY
  event_id, op

The hot read is "Ben's events overlapping this week": WHERE calendar_id = ? AND span_end_utc > week_start AND span_start_utc < week_end. The index skips everything that ended before this week, so years of history cost nothing; what is left is upcoming events, trimmed to this week by the start filter, plus a few dozen open-ended series to expand. Entries carry a copy of the times, rule and exceptions, so the read never leaves Ben's shard.

A relational database, sharded by calendar, fits: an edit changes the event, its exceptions and the change log atomically, which needs transactions on one shard, and the read is an indexed range scan.

#High-level design

The organizer's write is synchronous and small. Everything that touches other people happens after the reply, through a stream, so 40 guests do not mean 40 writes before Ana sees "Saved".

#Deep dives

#Repeating events and time zones

"Every weekday at 9:00, no end date" has infinitely many occurrences. You cannot store them all, and storing a few years of them hurts the moment someone edits the series.

Store the rule in the iCalendar RRULE format, the start as local time plus a zone, and exceptions keyed by the original start time of the occurrence they change. That key never changes, even when the occurrence moves. Here is Ana's series for March 2027, with March 8 cancelled and March 22 moved to 10:00:

Edit scopes map to the data: "this occurrence" adds an exception; "all" changes the series row; "this and following" splits the series, ending the old rule before the chosen occurrence and starting a new series there. Reads cap the window at a year, so expansion is always bounded.

Look at the UTC column. Ana's meeting stays at 9:00 in New York, so it moves an hour in UTC when New York changes its clocks on March 14, 2027. London changes on March 28, so for two weeks Ben sees 13:00, then 14:00 again. That is correct, and it only happens if you expand in the event's own zone, then convert.

• Repeating events store a local time and a zone name such as America/New_York, never an offset like −05:00, which is right for only half the year.
• All-day events are dates with no zone. A birthday on March 3 is March 3 everywhere.
• Missing and doubled times: 2:30 on the spring-forward night does not exist; 1:30 on the fall-back night happens twice. Use one rule on every server and device, such as iCalendar's for a single date-time: move a missing time forward by the gap, take the first of a doubled one.
• The rules change. Governments change daylight saving at short notice. Because you stored local time and a zone, a time zone database update fixes future occurrences on the next expansion. Anything derived in UTC (span columns, busy caches, planned reminders) must be rebuilt for that zone.

#Free/busy for many people

Chen asks when Ana, Ben and five others are free next week: seven shards, each with repeating events to expand. The answer needs only busy intervals, never titles: free/busy reveals when, not what.

The lookup reads 7 small entries in parallel, merges the sorted intervals (the intervals pattern) and returns the gaps inside working hours. For 100 million users the cache is 100 million × 3.6 KB ≈ 360 GB, a modest cluster. Entries lag changes by a few seconds, which is fine for suggesting slots.

#Reminders at scale

A repeating event has no last reminder, so reminders cannot all be scheduled up front. Use a rolling horizon on top of a job scheduler:

• Plan: a daily planner expands each calendar's next 48 hours, and fan-out workers plan new or changed occurrences inside that window. Jobs are keyed by (calendar, event, original start, offset), so planning twice creates one job.
• Re-check on fire: when a job fires, the worker reads the entry and drops the reminder if the event was cancelled, moved or declined. Cancellation becomes a cheap check instead of a hunt for jobs to delete.
• Survive the burst: 6 million reminders due at 9:50 is 100,000 a second for a minute. The scheduler loads each minute's jobs a minute early and hands them to the notification system, whose queues are built for bursts.
• Use the device: a synced phone can raise the alarm itself, so a server outage at 9:50 does not silence most reminders.

The scheduler runs jobs at least once, so a crash can repeat a reminder. A "sent" record per job key catches most repeats; a rare double beats a missed meeting.

#Edits from many devices

Every edit sends If-Match with the version it started from, and one conditional update applies it only if the version is unchanged. A stale edit gets 412 and the current event; the client merges field by field (phone changed the time, laptop the title: keep both) and retries, or asks the user if both changed one field.

Devices sync from the per-calendar change log. Each change takes the next number from a per-calendar counter in the same transaction, so numbers commit in order and "everything after 1,042" misses nothing; the sync token is that number. Log rows older than about 30 days are trimmed, and an older token gets 410 and a full resync. The push is only a nudge: if it is lost, the next app open syncs anyway.

#Bottlenecks and failures

At 10x (35,000 writes and 350,000 reads a second at peak), add calendar servers and read replicas (owners read their own calendar from the primary), and split shards by calendar. The first real pain is a huge guest list: an all-hands for 50,000 people is 50,000 entry writes per edit. Above about 1,000 guests, give each guest only a pointer row, written once, and read the times from the one shared event: the hybrid a news feed uses for accounts with millions of followers.

#What a strong answer sounds like

#Follow-up questions

#How do you book a meeting room without double booking?

A room is a calendar that accepts automatically if no confirmed occurrence overlaps. The check and the accept run in one transaction that also bumps the room's change counter, so two bookings for that room cannot interleave. The loser sees "declined".

#How do invites to people at other companies work?

By email with an iCalendar attachment. Replies come back the same way, matched by the event's unique ID and sequence number.

#An attendee declines one occurrence. Where is that stored?

As an exception on that attendee's entry, keyed by the original start; the shared event is untouched.

#How do you search a calendar by title?

Feed the change stream into a search index partitioned by calendar. Search returns series; the view expands them.

#How would you run this in several regions?

Home each calendar in one region and send its writes there, so versions and change logs stay simple. Replicate reads and the busy cache elsewhere, accepting a second of lag.