Design a Calendar System

The ask

An event has a title, a start time, an end time and a place. An event may invite guests.

Owners view events by day, week or month. Owners also ask when every guest is free.

Guests accept or decline an invitation. Changes by the organiser reach every guest.

Reminders fire before events. Times must stay right across time zones and clock changes.

Estimate the scale

The service holds calendars for 500,000,000 users.

1,000,000,000 events are stored.

Reminders tied to events fire 100,000,000 times a day.

100,000,000 / 86,400 = 1,157 reminders per second.

API and data

The create operation takes the title, the start, the end, the time zone, the guests and the place.

Read operations list events inside a time range and answer free-or-busy for a set of users. Update and delete operations name one event.

An event record holds its owner, its times, its guests and its reminder choices. Guest replies are stored on the record.

Start times are stored in one universal time form. The owner's time zone is stored beside the event for display.

High-level design

A calendar service owns event writes and range reads. Event stores are sharded by owner.

An invite worker delivers invitations and organiser changes to guests. Delivery rides a queue, so a slow guest mailbox never blocks a write.

A reminder engine receives each event's reminder times. Firing itself is a separate timing system.

Range reads hit an index by owner and start time. A month view reads one owner's slice only.

Deep dive: recurring events

A recurring event stores one rule, such as every Tuesday, plus a start and an end or a count. The rule is the event.

Occurrences are expanded only inside the requested range. A rule with no end is never expanded in full.

An exception record names one occurrence by its original time. The exception marks that occurrence skipped or moved.

Editing asks one plain question. The change applies to one occurrence or to the whole series.

A series edit rewrites the rule and keeps past exceptions that still match. Guests receive the updated expansion.

Invites and free time

Each guest calendar holds a reference to the same event. One organiser change updates one record and fans out a notice.

Free-or-busy reads return blocked ranges without titles. Privacy holds even inside one company.

Two events may overlap on one calendar. The system warns on a clash and lets the owner decide.

Time zones and reminders

A floating event, such as a daily standup at nine, follows the local clock. A fixed event keeps its universal time.

The record states which kind an event is. Display converts universal time through the viewer's time zone.

Reminder times are computed from the event start and stored with the event. The firing engine loads them by due time.

Evaluation and trade-offs

A calendar system is a range store with rules for repetition. The rule, not a pile of copies, is the heart of the design.

Expanding on read costs compute on every view. Storing every occurrence costs storage and makes series edits rewrite many rows.

Sharding by owner makes personal views fast. Free-or-busy across many owners reads many shards, and stays a narrow query.

Warnings on clashes keep control with the owner. Hard refusal would break legitimate double bookings.

Calendar scale