Design a calendar

Design a shared calendar like Google Calendar or Outlook: events, meetings that repeat every week, invitations, finding a time that suits twelve people in four time zones, booking rooms, and reminders that arrive at the right minute. The data is small; the hard parts are time itself (repeating series, time zones, clock changes) and the burst of reminders just before every hour.

1. The prompt

"Design a calendar for a workplace suite: people create events and meetings, invite others, see each other's free and busy times, book rooms and get reminders."

What makes it hard:

• Series without an end. "Every Monday at 9:00, forever" can't be stored as rows, yet "show me March" must be fast, and one Monday can be moved or cancelled on its own.
• Time zones and clock changes. A weekly 9:00 meeting must stay at 9:00 for the organiser when the clocks change, which means it moves for colleagues in countries that change on a different date.
• Everyone at once. Meetings start on the hour, so reminders, notifications and calendar loads arrive in sharp peaks just before :00 and :30.

2. Frame the problem

3. What it must do

1. Create and change events, including repeating ones, with exceptions for single occurrences.
2. Invite people and rooms; they accept or decline; the organiser sees replies.
3. Show calendars for any date range, and find a time using free/busy.
4. Remind each attendee at their chosen time before each occurrence.

Not now: video-call links (an external service), tasks and to-dos, AI scheduling assistants, public event discovery.

4. How well it must do it

5. Numbers that change the design

Illustrative numbers.

6. The nouns

• Calendar: belongs to a person, a room or a team; has a default time zone and sharing rules.
• Event: title, start and end as local time plus a time-zone name, an optional repeat rule, organiser, attendees.
• Exception: one occurrence of a series that was moved, edited or cancelled, identified by its original start.
• Occurrence: a concrete start and end in UTC, computed from an event and its rule. Stored only in indexes, never as the source of truth.
• Attendee: a person or room on an event, with a response.
• Reminder: who, which occurrence, when (in UTC), how.

event          (calendar_id, event_id) → organizer, title, start_local, end_local, tz ('Europe/London'),
               rrule ('FREQ=WEEKLY;BYDAY=MO'), until?, version, updated_at
exception      (event_id, original_start) → cancelled | new start/end/title
attendee       (event_id, user_or_room_id) → response (needs-action | yes | no | maybe)
occurrence_idx (calendar_id, day_utc) → [(event_id, start_utc, end_utc)]      (materialised 12 months ahead)
busy           (user_id, start_utc, end_utc, event_id)                         (free/busy read model)
reminder       (due_minute, shard) → [(user_id, event_id, occurrence_start, channel)]
change_log     (calendar_id, seq) → event_id, kind                              (sync tokens)

7. The contract

POST  /v1/calendars/{cal}/events              {title, start: {local, tz}, end, rrule?, attendees[], reminders[]} → event
PATCH /v1/events/{id}?scope=one|following|all  {changes, occurrence_start?}   (If-Match: version)
GET   /v1/calendars/{cal}/events?from=…&to=…  → occurrences, in the viewer's time zone
POST  /v1/freebusy                             {users[], rooms[], from, to} → busy ranges per person
POST  /v1/events/{id}/responses                {occurrence_start?, response}
GET   /v1/calendars/{cal}/changes?sync_token=… → changed and deleted events, next token (410 → full resync)

The organiser and responder come from the auth token. If-Match stops two people editing the same meeting from silently overwriting each other (Module 07).

8. First working version

An events service owns events, exceptions and attendees in a relational store sharded by calendar. Every change also writes a row to an outbox (Module 22), from which workers update the read models: the per-calendar occurrence index, the free/busy table, invitations (through the notification system, D05) and the reminder schedule.

8.1 Creating a weekly meeting

8.2 Opening your week

9. Make it hold up

9.1 Repeating events: a rule plus exceptions speed · correctness

Three kinds of edit. This occurrence: write an exception keyed by its original start. All occurrences: change the event and keep the exceptions that still make sense. This and following: end the old series the day before (set its until) and create a new series from that date, so the history before the change stays as it was.

9.2 Time zones and clock changes correctness

Store a repeating event's start as local time plus a time-zone name (09:00, Europe/London), never as a fixed UTC instant. Each occurrence is converted to UTC when expanded, using the IANA time-zone database. A single event in the future also keeps its zone name, because governments change their rules with little notice and the stored UTC instant would then be wrong.

The effect people notice: countries change their clocks on different dates. The US moves in early-to-mid March; the UK and EU at the end of March; south-eastern Australia in April and October; India and Brazil not at all. For those weeks, a meeting fixed in London time moves by an hour for colleagues in New York. That is correct, and the calendar should show it. The lab in section 13 shows it week by week.

• Two clock-change traps: a 02:30 event on the spring-forward day doesn't exist (move it to 03:30); one on the fall-back day happens twice (pick the first).
• All-day events are dates, not times: a birthday on 14 March must not become 13 March for a viewer in another zone.
• Keep the time-zone database up to date on every server and client, and re-expand affected series when it changes.

9.3 Finding a time for twelve people speed · privacy

The busy table is a read model: one row per occurrence per attendee who accepted or hasn't answered, with no titles. Permission to see free/busy is checked once per person; permission to see details is a separate, stricter check. Working hours and time zones come from each person's settings, so the search only offers slots inside everyone's day.

9.4 Rooms that can't be double-booked consistency

A room is an attendee with its own calendar, and booking it must be atomic. For single events, a database range constraint on the room's bookings (PostgreSQL's exclusion constraint on a time range, as in D15's stays variation) refuses an overlap. For a repeating booking, the service expands the next 12 months, checks every occurrence and inserts them all in one transaction; occurrences beyond that are booked by the nightly job, and a clash found then is reported to the organiser. Popular rooms are contended at round hours, so the booking path is short: no external calls inside the transaction.

9.5 Five million reminders at 09:50 load shape

9.6 Huge meetings and phones that sync scale · freshness

• Huge meetings. Writing an occurrence-index row and a busy row for each of 300,000 attendees takes minutes and is redone on every change. Above a threshold (say 1,000 attendees), the event is stored once, attendees reach it through a "large events I'm invited to" list read at view time, and their busy rows are written lazily, only when someone asks for their free/busy.
• Phones. Each calendar has a change log with an increasing sequence number. A phone sends its last sync token and receives only events changed or deleted since; if the token is too old, the server answers 410 Gone and the phone does a full sync. The same log feeds web clients' live updates over a WebSocket.
• Standard apps connect through CalDAV and iCalendar, which map directly onto events, rules and exceptions: one reason to model them the standard's way.

9.7 The whole design after the deep dives

10. Interviewer follow-ups

11. When things break

12. Wrap-up and the clock

Trade-offs we made:

• Rules and exceptions as the truth, plus a derived 12-month index: small truth, fast reads, a nightly job to keep it extended.
• Local time plus a zone name, not UTC, for anything that repeats or lies in the future.
• Separate read models (occurrences, busy, reminders) fed from an outbox: eventually consistent by seconds, simple writes.
• Database-enforced room bookings, keeping that transaction short.
• Huge meetings read on demand instead of fanned out.

What we'd watch: week-view p99 · outbox age · reminder delay at :50 and :20 · room-booking conflicts · sync 410 rate · time-zone database version across servers.

At 10×: more shards; the reminder minute is the first thing to grow, so more shards per bucket and more workers. The model doesn't change.

Common mistakes:

• Storing every occurrence of a series as a row.
• Storing repeating times in UTC, so meetings drift by an hour twice a year.
• Treating all-day events as midnight UTC.
• Ignoring the burst of reminders before each hour.
• Checking room availability and then inserting, without a constraint.

13. Try it, check yourself, read more

The clock-change lab. A weekly meeting is created by an organiser in one city. Pick where they are, the meeting time, and where a colleague is. Then compare storing it as local time plus a zone name with storing a fixed UTC time.

Computed in your browser with its own time-zone database, for Mondays from 2 March to 4 May 2026.