Design Google Calendar

A planet-scale calendar is three coupled problems wearing one product skin: temporal data modelling (events, recurrence rules, exceptions), timezone arithmetic (the same event at the right local time across DST boundaries and a moving user base), and availability computation (finding meeting slots across many calendars in tens of milliseconds). This article designs a system around those three axes, leaning on the iCalendar family of RFCs (RFC 5545, 5546, 6047, 4791, 6638, 6578) and on the publicly documented behaviour of the Google Calendar API.

Mental model

Three concepts carry the rest of the article:

• Recurrence master vs. instance. A recurring series is one row carrying an RRULE (e.g. FREQ=WEEKLY;BYDAY=MO,WE,FR) plus DTSTART;TZID=…. An instance is one occurrence of that series at a concrete moment. Instances are usually computed, not stored — except where the user has overridden one (an exception), in which case it lives as its own row keyed by the master’s id and the original start time. This is exactly how the Google Calendar API exposes recurring events: instances carry recurringEventId and originalStartTime, and a deleted occurrence appears as status: "cancelled" rather than as an EXDATE on the master.¹
• Local time + named TZID, not UTC. A “9 AM daily standup” is a local-time recurrence. RFC 5545 §3.3.5 stores DATE-TIME values with a TZID parameter (a name from the IANA Time Zone Database) and resolves UTC offset at render time using the VTIMEZONE rules. Storing the start as a UTC instant silently breaks every recurring event the moment its DST rule fires.
• Sync-token, not poll. CalDAV and the Google Calendar API both expose monotonic sync-tokens (RFC 6578) so a client can ask “what changed since state X?” instead of refetching the whole calendar. When the server can no longer answer that question — token aged out, ACL changed, calendar reindexed — it returns 410 Gone and the client must do a full sync.²

The rest of the article is a tour of how those three primitives drive the architecture, the API, the storage layout, and the failure modes.

Requirements

Functional requirements

Non-functional requirements

Scale estimation

These numbers are illustrative — Google does not publish exact Calendar MAU — but they are the right order of magnitude for sizing a planet-scale design.

Users

• MAU: 500 M (Workspace + consumer Gmail).
• DAU: 100 M.
• Peak concurrent: ~10 M (10% of DAU).

Events

• Average per user: 50 active recurring + 200 single events.
• Total event records: 500 M × 250 ≈ 125 B logical instances but only ≈ 25 B master rows because we store recurrence rules, not expansions.

Traffic

• Calendar loads: 100 M DAU × 10/day ≈ 12 K RPS.
• Event writes: 100 M DAU × 2/day ≈ 2.3 K RPS.
• Free/busy queries: 100 M DAU × 0.5/day ≈ 580 RPS.
• 3× peak multiplier → ~36 K read RPS, ~7 K write RPS.

Storage

• Master row ≈ 2 KB (metadata, description, RRULE, attendees).
• 25 B × 2 KB ≈ 50 TB primary, ~200 TB with indexes, replicas, and history.

Recurrence storage: RRULE-only, instances-only, or hybrid

There are three defensible strategies. The article picks the third; the trade-off table below is the reason.

Path A — RRULE-centric (store rules, expand on read)

• Store only the recurrence rule on the master.
• Expand instances dynamically when a query asks for a date range.
• Cache expansion results in Redis for hot calendars.

Pros: minimal storage; series updates propagate instantly; supports infinite recurrence naturally. Cons: CPU-heavy for complex RRULEs; slow over long ranges; exception handling adds query complexity. Open-source CalDAV servers (Radicale, DAViCal) lean here because storage cost dominates for personal calendars.

Path B — instance-centric (materialize all)

• Pre-expand every instance into a separate table.
• Series modifications fan out to thousands of rows.
• Range queries become a single B-tree scan.

Pros: O(1)-shaped range queries, simple free/busy aggregation, exception is just a row with overrides. Cons: storage explosion (a daily event for 10 years = 3,650 rows), expensive series updates, no natural infinite recurrence. Best fit for enterprise scheduling backends where read latency dominates and series are rarely “infinite” — though most real systems (Exchange included) actually keep the recurrence pattern alongside materialized occurrences and live in Path C.

Path C — hybrid (chosen)

• Store recurrence rules on the master.
• Materialize instances for a rolling window (typically 30–90 days).
• Expand dynamically beyond the window.
• Refresh the materialized window with a nightly background job.

Pros: fast queries inside the window, bounded storage per series, infinite recurrence still works, series updates only touch the window. Cons: two code paths; staleness possible if the background refresher lags.

Path comparison

The hybrid model fits the realistic workload mix: most reads are “this week / this month” inside the window, and the long tail of “show me everything in 2031” can absorb the cost of dynamic expansion.

High-level design

Service responsibilities

Event service

CRUD for event masters and exceptions:

• Create / update / delete single events.
• Create / update / delete recurring series (stores RRULE + EXDATE/RDATE).
• Create exception rows (modified or cancelled occurrences).
• Range queries: hits the materialized window directly; calls the recurrence service for ranges beyond.

Recurrence service

Expands RRULE strings into instances per RFC 5545 §3.8.5.3:

• Parse the RRULE.
• Generate occurrences in the requested range, in the master’s TZID.
• Apply EXDATE (exclusions) and RDATE (additions).
• Merge with exception rows from Postgres.
• Cache expansions in Redis (TTL ≈ 1 h for hot series).

Scheduling service

Meeting coordination:

• Aggregate free/busy across attendees and resources.
• Find available slots within a working-hours window.
• Send invitations as iTIP REQUEST messages (RFC 5546 §3.2.2).
• Process RSVPs as iTIP REPLY messages.
• Resource booking (rooms, equipment).

Sync service

Multi-client synchronisation:

• Implement CalDAV (RFC 4791) and the CalDAV scheduling extensions (RFC 6638).
• Maintain monotonic sync-tokens per calendar via the WebDAV DAV:sync-collection report (RFC 6578).
• Push real-time updates over WebSocket / FCM / APNs.
• Detect and surface conflicts.

Notification service

Reminder and alert delivery:

• Schedule reminders from VALARM properties.
• Deliver via push, email, or SMS.
• Apply timezone-aware fan-out (a 9 AM local reminder for an event hops timezones with the user).
• Batch and deduplicate at delivery time.

Create a recurring event

Query a calendar view

API design

The REST surface mirrors the Google Calendar API closely so clients are familiar; the underlying mechanics map 1:1 to iCalendar primitives.

Event resource

Create event

POST /api/v1/calendars/{calendarId}/events

Show 3 hidden lines45// Request body6{7  "summary": "Weekly Team Standup",8  "description": "Discuss blockers and priorities",9  "start": {10    "dateTime": "2026-01-15T09:00:00",11    "timeZone": "America/New_York"12  },13  "end": {14    "dateTime": "2026-01-15T09:30:00",15    "timeZone": "America/New_York"16  },17  "recurrence": ["RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR"],18  "attendees": [19    { "email": "alice@example.com" },20    { "email": "bob@example.com", "optional": true }21  ],22  "reminders": {23    "useDefault": false,24    "overrides": [25      { "method": "popup", "minutes": 10 },26      { "method": "email", "minutes": 60 }27    ]28  },Show 7 hidden lines36}

201 Created returns the canonical resource (id, ETag, server-resolved offsets, conference link, etc.). The shape is documented in the Google Events resource reference.

Error responses

• 400 Bad Request — invalid RRULE syntax, missing required fields.
• 401 Unauthorized — missing or invalid auth token.
• 403 Forbidden — no write access to calendar.
• 409 Conflict — strict-mode collision with an existing event.
• 429 Too Many Requests — rate limit exceeded.

Rate limits: 600 requests / minute / user, 10,000 requests / minute / project (mirroring Google’s published quotas).

Query events

GET /api/v1/calendars/{calendarId}/events

Why cursor-based, not offset-based: calendar data churns constantly, so offset pagination silently skips or duplicates rows when the underlying set changes between pages. Sync tokens additionally enable incremental sync — the client gets only changes since the previous token.

Sync flow

1. Initial full sync: GET /events?timeMin=…&timeMax=… → returns nextSyncToken.
2. Incremental sync: GET /events?syncToken={token}&showDeleted=true → returns changed items + new nextSyncToken.
3. If the token is no longer valid (410 Gone): wipe local state and re-do the initial full sync. The Google Calendar API does not document a fixed expiration; tokens may also be invalidated by ACL changes or server-side reindexing,² so clients must always be ready to recover.

Modify a single instance of a recurring event

PUT /api/v1/calendars/{calendarId}/events/{recurringEventId}/instances/{instanceId}

This creates an exception that overrides one occurrence:

1{2  "start": { "dateTime": "2026-01-17T10:00:00", "timeZone": "America/New_York" },3  "end":   { "dateTime": "2026-01-17T10:30:00", "timeZone": "America/New_York" }4}

The instanceId encodes the original start time (e.g. abc123_20260117T140000Z).

How exceptions are stored. The exception is a separate row linked to the master via recurring_event_id (a.k.a. recurringEventId) and pinned to the original_start_time. That gives three properties at once:

• the modified instance is queryable by its new time;
• deleting the exception reverts to the original time;
• a deleted occurrence is just an exception with status = 'cancelled' — no EXDATE mutation on the master.¹

Free/busy query

POST /api/v1/freeBusy

1{2  "timeMin": "2026-01-15T00:00:00Z",3  "timeMax": "2026-01-22T00:00:00Z",4  "items": [5    { "id": "alice@example.com" },6    { "id": "bob@example.com" },7    { "id": "conference-room-a@resource.example.com" }8  ]9}

Response (only the busy intervals — never event details):

Show 3 hidden lines4  "timeMax": "2026-01-22T00:00:00Z",5  "calendars": {6    "alice@example.com": {7      "busy": [8        { "start": "2026-01-15T14:00:00Z", "end": "2026-01-15T15:00:00Z" },9        { "start": "2026-01-16T09:00:00Z", "end": "2026-01-16T10:00:00Z" }10      ]11    },12    "bob@example.com": {13      "busy": [{ "start": "2026-01-15T14:00:00Z", "end": "2026-01-15T14:30:00Z" }]14    },15    "conference-room-a@resource.example.com": {16      "busy": [{ "start": "2026-01-15T10:00:00Z", "end": "2026-01-15T11:00:00Z" }],17      "errors": []18    }19  },20  "groups": {}21}

Privacy. Free/busy never leaks event content. The transparency field on the underlying event controls whether the time even appears as busy: opaque (default) blocks the time, transparent does not (e.g. an all-day “working from home” marker). This mirrors the CalDAV CALDAV:free-busy-query REPORT (RFC 4791 §7.10) which returns VFREEBUSY components only.

Data modeling

Event schema

PostgreSQL is the primary store: ACID writes, range queries, and a rich type system are the ergonomic fit; the recurrence machinery sits in application code, not the database.

Show 3 hidden lines4    email VARCHAR(255) UNIQUE NOT NULL,5    timezone VARCHAR(50) DEFAULT 'UTC',6    created_at TIMESTAMPTZ DEFAULT NOW()7);89CREATE TABLE calendars (10    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),11    owner_id UUID NOT NULL REFERENCES users(id),12    name VARCHAR(255) NOT NULL,13    timezone VARCHAR(50) NOT NULL,14    sync_token BIGINT DEFAULT 0,15    created_at TIMESTAMPTZ DEFAULT NOW()16);1718-- Event master table (single + recurring)19CREATE TABLE events (20    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),21    calendar_id UUID NOT NULL REFERENCES calendars(id),22    ical_uid VARCHAR(255) NOT NULL,  -- RFC 5545 UID for iCal interop23    summary VARCHAR(500),24    description TEXT,25    location VARCHAR(500),2627    -- Local time + named TZID, per RFC 5545 §3.3.528    start_datetime TIMESTAMP NOT NULL,29    end_datetime TIMESTAMP NOT NULL,30    start_timezone VARCHAR(50) NOT NULL,31    end_timezone VARCHAR(50) NOT NULL,32    is_all_day BOOLEAN DEFAULT FALSE,3334    -- Recurrence (NULL for single events)35    recurrence_rule TEXT,            -- RRULE string36    recurrence_exceptions TEXT[],    -- EXDATE37    recurrence_additions TEXT[],     -- RDATE3839    -- Metadata40    status VARCHAR(20) DEFAULT 'confirmed',41    visibility VARCHAR(20) DEFAULT 'default',42    transparency VARCHAR(20) DEFAULT 'opaque',43    sequence INTEGER DEFAULT 0,      -- iCal SEQUENCE (incremented on update)44Show 11 hidden lines56    WHERE deleted_at IS NULL;57CREATE INDEX idx_events_updated ON events(calendar_id, updated_at)58    WHERE deleted_at IS NULL;59CREATE INDEX idx_events_recurring ON events(calendar_id)60    WHERE recurrence_rule IS NOT NULL AND deleted_at IS NULL;

Why local time + TZID instead of UTC

1. DST correctness. A “9 AM daily standup” must stay at 9 AM local time; storing UTC silently shifts it by an hour twice a year.
2. RRULE semantics. BYDAY=MO means Monday in the event’s timezone, not UTC Monday — which differs in the western Pacific.
3. Display simplicity. No round-trip conversion when rendering in the organizer’s zone.

The trade-off is that cross-timezone range queries need conversion. The materialized instances table stores computed UTC times so range scans can use a B-tree index without per-row conversion.

Materialized instances

Show 3 hidden lines4    event_id UUID NOT NULL REFERENCES events(id) ON DELETE CASCADE,5    calendar_id UUID NOT NULL REFERENCES calendars(id),67    instance_start_utc TIMESTAMPTZ NOT NULL,8    instance_end_utc   TIMESTAMPTZ NOT NULL,910    -- Original occurrence date — used to match exceptions to the master11    original_start_utc TIMESTAMPTZ NOT NULL,1213    -- NULL fields inherit from the master14    summary_override     VARCHAR(500),15    description_override TEXT,16    location_override    VARCHAR(500),17    start_override       TIMESTAMP,18    end_override         TIMESTAMP,19    timezone_override    VARCHAR(50),2021    status        VARCHAR(20) NOT NULL DEFAULT 'confirmed',  -- confirmed | cancelled22    is_exception  BOOLEAN     DEFAULT FALSE,2324    created_at TIMESTAMPTZ DEFAULT NOW()25);2627CREATE INDEX idx_instances_calendar_range28    ON event_instances(calendar_id, instance_start_utc, instance_end_utc)29    WHERE status != 'cancelled';Show 6 hidden lines36    ON event_instances(event_id, original_start_utc)37    WHERE is_exception = TRUE;

Attendees and RSVPs

Show 3 hidden lines4    email VARCHAR(255) NOT NULL,5    display_name VARCHAR(255),67    -- RFC 5545 PARTSTAT8    response_status VARCHAR(20) DEFAULT 'needsAction',9    -- needsAction | declined | tentative | accepted1011    is_organizer BOOLEAN DEFAULT FALSE,12    is_optional  BOOLEAN DEFAULT FALSE,13    is_resource  BOOLEAN DEFAULT FALSE,  -- conference room, equipment1415    response_comment TEXT,16    responded_at     TIMESTAMPTZ,1718    UNIQUE(event_id, email)19);2021CREATE INDEX idx_attendees_email ON event_attendees(email, event_id);22CREATE INDEX idx_attendees_event ON event_attendees(event_id);

Database selection matrix

Sharding

Shard key: calendar_id.

• Co-locates all events for a calendar — most queries filter by calendar.
• Calendar view queries hit a single shard.
• Cross-calendar queries (free/busy) become scatter-gather, but they are an order of magnitude rarer than per-calendar reads.

Hash-based sharding with 256 logical shards distributed across physical nodes; consistent hashing for rebalancing.

Low-level design

Recurrence expansion

The recurrence service expands RRULE strings into concrete instances per RFC 5545 §3.8.5.3. The algorithm itself is well-specified; the cost lives in the edge cases (DST, leap day, byday-with-monthday). The pipeline below shows how the master’s RRULE, its EXDATE / RDATE properties, and any exception rows collapse into the rendered series for a query.

Show 10 hidden lines11}1213function expandRecurrence(req: RecurrenceExpansionRequest): Date[] {14  const rule = RRule.fromString(req.rruleString)15  const set = new RRuleSet()16  set.rrule(rule)1718  for (const exdate of req.exdates ?? []) set.exdate(exdate)19  for (const rdate of req.rdates ?? []) set.rdate(rdate)2021  // CRITICAL: between() expands in the rule's timezone for DST correctness.22  return set.between(req.rangeStart, req.rangeEnd, true)23}2425const instances = expandRecurrence({26  rruleString: "FREQ=WEEKLY;BYDAY=MO,WE,FR",27  dtstart: new Date("2026-01-15T09:00:00"),28  timezone: "America/New_York",29  rangeStart: new Date("2026-01-01T00:00:00Z"),30  rangeEnd: new Date("2026-03-31T23:59:59Z"),31  exdates: [new Date("2026-01-17T09:00:00")],32})33// → [Jan 15, Jan 19, Jan 22, Jan 24, Jan 26, ...]

DST edge cases

Spring forward (the missing hour, e.g. 02:30 on the second Sunday in March in America/New_York)

Per the spec, a DATE-TIME whose local representation falls in the gap is interpreted using the UTC offset that was in effect immediately before the gap. So TZID=America/New_York:20260308T023000 is interpreted at -05:00 (EST), which is 07:30 UTC — the same UTC instant as 03:30 -04:00 (EDT). The visible local time the user sees post-transition is 03:30, not 02:30.

Show 5 hidden lines6  day: number7  hour: number8  minute: number9}1011// Resolve a TZID-bearing local time to a UTC instant per RFC 5545 §3.3.5.12// Construct from local components, NOT from a JS Date (which is already a13// UTC instant and therefore never ambiguous).14function resolveLocalDateTime(local: LocalComponents, timezone: string): DateTime {15  // Luxon's default disambiguation matches RFC 5545 in both directions:16  // - Spring-forward gap (e.g. America/New_York 2026-03-08T02:30): the wall17  //   clock is advanced into the post-transition offset (-04:00 EDT), so18  //   the resolved UTC instant is the same one the spec prescribes via the19  //   pre-gap offset interpretation (07:30 UTC).20  // - Fall-back overlap (e.g. America/New_York 2026-11-01T01:30): the21  //   earlier (pre-transition, -04:00 EDT) occurrence is selected.22  return DateTime.fromObject(local, { zone: timezone })23}

Fall back (the duplicated hour, e.g. 01:30 occurs twice in November)

RFC 5545 §3.3.5 prescribes that an ambiguous local time refers to the first occurrence — the pre-transition one (DST, -04:00 in America/New_York).

Operational consequence. Always carry both DATE-TIME and TZID through the system. A VTIMEZONE reference points at the IANA database, which encodes the full historical and future DST rule set. Libraries — Luxon, date-fns-tz, moment-timezone, python-dateutil — implement these rules correctly only because they consume tzdata. Keep tzdata upgrades in your release pipeline; a stale tzdata is the most common reason a calendar drifts after a country changes its DST rules (recent example: Egypt restoring DST in 2023).

Free/busy aggregation

Free/busy aggregation is the hot path of meeting scheduling. The latency target — under 100 ms for 10 attendees over a week — rules out per-request expansion of every attendee’s calendar. Pre-computed busy intervals in Redis sorted sets, scored by start timestamp, give the right shape: range scans are O(log N + M).

Show 8 hidden lines9// Storage: ZSET freebusy:{calendarId}, score = start, member = JSON({ start, end, eventId })1011async function updateFreeBusy(redis: Redis, calendarId: string, instances: EventInstance[]): Promise<void> {12  const key = `freebusy:${calendarId}`13  const pipeline = redis.pipeline()1415  const rangeStart = Math.min(...instances.map((i) => i.startUtc.getTime() / 1000))16  const rangeEnd   = Math.max(...instances.map((i) => i.endUtc.getTime() / 1000))17  pipeline.zremrangebyscore(key, rangeStart, rangeEnd)1819  for (const instance of instances) {20    if (instance.status === "confirmed" && instance.transparency === "opaque") {21      const interval: BusyInterval = {22        start: instance.startUtc.getTime() / 1000,23        end:   instance.endUtc.getTime() / 1000,24        eventId: instance.eventId,25      }26      pipeline.zadd(key, interval.start, JSON.stringify(interval))27    }28  }2930  pipeline.expire(key, 7 * 24 * 60 * 60)31  await pipeline.exec()32}3334async function queryFreeBusy(35  redis: Redis,36  calendarId: string,37  rangeStart: Date,38  rangeEnd: Date,39): Promise<BusyInterval[]> {Show 9 hidden lines

Finding available slots

A standard interval-merge then gap-scan: union every attendee’s busy intervals, sort by start, fold overlaps, and emit the gaps that are at least the requested duration. The diagram below shows the same algorithm visually for three calendars over a working window.

Show 5 hidden lines6  rangeEnd: Date,7  durationMinutes: number,8  workingHours?: { start: number; end: number },9): TimeSlot[] {10  const all: BusyInterval[] = []11  for (const intervals of busyByAttendee.values()) all.push(...intervals)1213  all.sort((a, b) => a.start - b.start)1415  // Merge overlapping intervals16  const merged: BusyInterval[] = []17  for (const iv of all) {18    const last = merged[merged.length - 1]19    if (!last || last.end < iv.start) merged.push({ ...iv })20    else last.end = Math.max(last.end, iv.end)21  }2223  const durationSec = durationMinutes * 6024  const free: TimeSlot[] = []25  let cursor = rangeStart.getTime() / 10002627  for (const busy of merged) {28    if (busy.start - cursor >= durationSec) {29      free.push({ start: new Date(cursor * 1000), end: new Date(busy.start * 1000) })30    }31    cursor = Math.max(cursor, busy.end)32  }3334  const endSec = rangeEnd.getTime() / 100035  if (endSec - cursor >= durationSec) {36    free.push({ start: new Date(cursor * 1000), end: rangeEnd })37  }3839  if (workingHours) {40    return free.filter((slot) => {41      const h = slot.start.getHours()42      return h >= workingHours.start && h < workingHours.end43    })44  }45  return free46}

Complexity: O(N log N) for the sort, O(N) for the merge, where N is the total busy interval count across all attendees.

Sync token implementation

CalDAV’s incremental sync is built on the WebDAV DAV:sync-collection REPORT (RFC 6578 §3): the client sends its last sync-token, the server returns the changed members plus a fresh token. The semantics of the token are deliberately opaque — the server is free to use a monotonic integer, an LSN, or any other state identifier the implementation can resolve back to a change set.

Show 5 hidden lines6    changed_at TIMESTAMPTZ DEFAULT NOW(),7    sync_token BIGINT NOT NULL          -- matches calendars.sync_token at change time8);910CREATE INDEX idx_changes_sync ON calendar_changes(calendar_id, sync_token);1112CREATE OR REPLACE FUNCTION record_event_change()13RETURNS TRIGGER AS $$14BEGIN15  UPDATE calendars SET sync_token = sync_token + 1 WHERE id = NEW.calendar_id;16  INSERT INTO calendar_changes (calendar_id, event_id, change_type, sync_token)17  SELECT NEW.calendar_id, NEW.id, TG_OP, sync_token18  FROM calendars WHERE id = NEW.calendar_id;19  RETURN NEW;20END;21$$ LANGUAGE plpgsql;

Sync flow

1. Initial sync: client gets all events + current syncToken (e.g. 15).
2. Incremental sync: client sends syncToken=15, server returns rows where sync_token > 15 plus the new token (e.g. 23).
3. Token invalidation (410 Gone): the change-log entry has been compacted, the calendar ACL changed, or the server simply chose to invalidate. Client wipes its local state and does step 1 again. Google’s documentation does not promise a fixed token lifetime — clients must always handle 410.²

For server-to-server consumers (a CalDAV-style integration, a downstream automation), the Google Calendar API also exposes a watch + webhook model: a POST .../events/watch registers a notification channel with an HTTPS callback URL; when a change occurs, Google sends a signal-only POST carrying X-Goog-Resource-State and X-Goog-Resource-URI headers but no event body, and the consumer is expected to immediately call events.list?syncToken=… to fetch the actual delta.³ Channels expire (default 1 week) and must be renewed; reliability is best-effort, so a low-frequency periodic full sync remains the safety net.

Notification fan-out

A single change must reach many surfaces — open browser tabs, iOS / Android apps in background, third-party watch channels, and (for invitations) external mailboxes — without each one polling. The pattern is the same one used for any large fan-out write: commit, publish to a durable change topic, and let a fan-out worker resolve the per-attendee subscription set against a registry of live channels.

Two design choices fall out of this shape:

• Signal, don’t ship payloads. The push carries enough metadata for the client to ask “what changed?” but never the event body. That keeps payloads tiny, sidesteps end-to-end encryption concerns on third-party push infrastructure, and keeps the source of truth on the server (one sync-token-driven path, not two divergent representations).
• Idempotent reconcile, at-least-once delivery. WebSockets reconnect, FCM/APNs retry, watch channels duplicate. The reconciliation path is a GET /events?syncToken=… whose result is purely a function of the server-side change log, so duplicate signals collapse to a single no-op fetch.

Invitation workflow (iTIP / iMIP)

When the organiser invites attendees, the system emits an iTIP REQUEST (RFC 5546 §3.2.2) wrapped in an iMIP-formatted email (RFC 6047).

The iMIP wire format is a multipart MIME message with a text/calendar; method=REQUEST part:

1Content-Type: multipart/alternative; boundary="boundary"23--boundary4Content-Type: text/plain56You've been invited to: Weekly Team Standup7When: Monday, January 15, 2026 9:00 AM - 9:30 AM (EST)89--boundary10Content-Type: text/calendar; method=REQUEST1112BEGIN:VCALENDAR13VERSION:2.014METHOD:REQUEST15BEGIN:VEVENT16UID:abc123xyz@calendar.example.com17DTSTART;TZID=America/New_York:20260115T09000018DTEND;TZID=America/New_York:20260115T09300019SUMMARY:Weekly Team Standup20ORGANIZER:mailto:organizer@example.com21ATTENDEE;PARTSTAT=NEEDS-ACTION:mailto:attendee@example.com22END:VEVENT23END:VCALENDAR2425--boundary--

A native CalDAV client takes a different path — the CalDAV scheduling extensions (RFC 6638) deliver REQUEST and REPLY server-side via inboxes/outboxes on each user’s calendar home, avoiding the email round-trip entirely.

Frontend considerations

Calendar view performance

A month view with recurring events can show hundreds of instances. The win is virtualization plus range-buffered loading.

Show 10 hidden lines11    events: new Map(),12  })1314  useEffect(() => {15    const rangeToLoad = expandRange(state.visibleRange, { days: 7 })  // ±1 week buffer1617    if (!isRangeCovered(rangeToLoad, state.loadedRanges)) {18      fetchEvents(calendarId, rangeToLoad).then((newEvents) => {19        setState((prev) => ({20          ...prev,21          loadedRanges: mergeRanges([...prev.loadedRanges, rangeToLoad]),22          events: new Map([...prev.events, ...newEvents.map((e) => [e.id, e])]),23        }))24      })25    }26  }, [state.visibleRange, calendarId])2728  return state.events29}

Plus the usual list of cheap wins:

• Pass singleEvents=true so the server returns pre-expanded instances.
• Cache by date range — events inside a past range almost never change.
• Use ETag / If-None-Match for conditional refetches.
• Virtualize day cells in month view (render only visible weeks).

Real-time updates

WebSocket for active browser tabs, push (FCM/APNs) for backgrounded clients. Both deliver the same change envelope: { type, eventId, ... } plus a fresh sync-token so the client can reconcile.

Show 5 hidden lines67    ws.onmessage = (event) => {8      const change = JSON.parse(event.data)9      switch (change.type) {10        case "event.created":11        case "event.updated":12          queryClient.setQueryData(["events", calendarId], (old: CalendarEvent[]) =>13            upsertEvent(old, change.event),14          )15          break16        case "event.deleted":17          queryClient.setQueryData(["events", calendarId], (old: CalendarEvent[]) =>18            old.filter((e) => e.id !== change.eventId),19          )20          break21      }22    }2324    return () => ws.close()Show 2 hidden lines

Timezone display

User expectations:

• Event times shown in the user’s local timezone by default.
• Optional view in the event’s original timezone.
• All-day events span the full day in any timezone — no conversion.

Show 5 hidden lines6  }78  const start = DateTime.fromISO(event.start.dateTime, { zone: event.start.timeZone })9  const userStart = start.setZone(userTimezone)1011  if (event.start.timeZone !== userTimezone) {12    return `${userStart.toLocaleString(DateTime.TIME_SIMPLE)} (${userStart.toFormat("ZZZZ")})`13  }1415  return userStart.toLocaleString(DateTime.TIME_SIMPLE)16}

Drag-and-drop rescheduling

Optimistic update with rollback for single events; for recurring events, always prompt for scope before issuing the mutation — “this event only”, “this and following”, or “all events”.

Show 5 hidden lines6    start: { dateTime: newStart.toISOString(), timeZone: old.start.timeZone },7    end:   { dateTime: newEnd.toISOString(),   timeZone: old.end.timeZone },8  }))910  try {11    await updateEvent(eventId, { start: newStart, end: newEnd })12  } catch (error) {13    queryClient.setQueryData(["event", eventId], previous)14    toast.error("Failed to reschedule event")15  }16}1718function handleRecurringEventDrop(eventId: string, instanceDate: Date, newTime: Date) {19  showDialog({20    title: "Edit recurring event",21    options: [22      { label: "This event only",         action: () => updateInstance(eventId, instanceDate, newTime) },23      { label: "This and future events",  action: () => splitSeries(eventId, instanceDate, newTime) },24      { label: "All events",              action: () => updateSeries(eventId, newTime) },25    ],26  })27}

Infrastructure design

Cloud-agnostic shopping list

AWS reference architecture

Self-hosted alternatives

Failure modes worth designing for

• Sync-token invalidation storm. A wide ACL change or a calendar reindex invalidates every active client at once. The recovery (full sync) is N× more expensive than incremental sync; protect the API tier with per-client backoff and cap concurrent full syncs per backend.
• Hot recurring series. A 5-minute standup with 200,000 attendees is one master row whose expansion is read by every attendee’s calendar view. Cache the expansion at the recurrence service, not just at the event service.
• Time-bomb RRULE. A user can create RRULE:FREQ=SECONDLY (technically valid). Reject server-side if the resulting expansion in any window exceeds a hard cap (e.g. 10,000 instances).
• Stale tzdata. A country changes its DST rule; until your tzdata package is upgraded and your services restarted, recurring events drift. Bake tzdata refreshes into the release pipeline and add a startup-time assertion against the expected version.
• Last-write-wins amnesia. Two clients edit the same event offline; on reconnect, the later write silently overwrites the earlier one. Surface the conflict to the user (using the SEQUENCE and LAST-MODIFIED properties from RFC 5545) instead of swallowing it.

Conclusion

The hybrid recurrence model — store rules, materialize a window, expand beyond it on read — keeps query latency bounded for the common case (this week / this month) while supporting infinite series cleanly. Three other choices carry their weight throughout the design:

1. Local time + TZID storage — events keep meaning across DST and time-zone-shifting users; UTC alone silently breaks recurring events.
2. Sync tokens — incremental sync is mandatory for CalDAV / mobile; clients must always handle 410 Gone and full-sync recovery.
3. Pre-computed free/busy in Redis — sub-100 ms scheduling queries fall out of an interval-merge over sorted sets, not out of an on-demand expansion at query time.

What this design deliberately does not solve, and where the next iteration should go:

• Real collaborative editing. Last-write-wins with surfaced conflicts is the practical floor; CRDT-based collaborative editing of event properties is a real next step but a larger commitment.
• Federated free/busy. Cross-organisation availability needs the iSchedule extensions and additional privacy controls.
• Smart scheduling. Suggesting good meeting slots from attendee patterns is a separable ML/analytics problem layered on top of the data model.

Appendix

Prerequisites

• Distributed-systems fundamentals (CAP, eventual consistency).
• Database design (indexing, sharding, replication).
• REST API design.
• Basic understanding of timezone concepts (UTC, offsets, DST).

Terminology

• RRULE — recurrence rule (RFC 5545 §3.8.5.3), e.g. FREQ=WEEKLY;BYDAY=MO.
• EXDATE / RDATE — exception / addition dates on a recurring series.
• RECURRENCE-ID — identifies which occurrence of a series an exception modifies.
• iTIP — iCalendar Transport-Independent Interoperability Protocol (RFC 5546): scheduling methods (REQUEST, REPLY, CANCEL).
• iMIP — iTIP over email (RFC 6047).
• CalDAV — calendar access on top of WebDAV (RFC 4791); scheduling extensions in RFC 6638.
• Sync token — opaque server state identifier for incremental sync (RFC 6578).
• TZID — IANA timezone name (e.g. America/New_York).

Summary

• Recurring events live as RRULE-bearing master rows; instances are materialized for a rolling 30–90-day window and expanded on demand beyond it.
• Time is stored as local-time + named TZID per RFC 5545 §3.3.5; never raw UTC, or DST silently breaks every recurring event.
• Free/busy is a Redis sorted-set workload; an interval-merge over the union answers “find me a slot” in O(N log N).
• Sync tokens (RFC 6578) make incremental sync cheap; clients must always handle 410 Gone and re-do a full sync.
• iTIP / iMIP (RFC 5546 / 6047) deliver invitations interoperably across vendors; CalDAV scheduling (RFC 6638) is the server-side alternative.
• Sharding by calendar_id co-locates the per-calendar working set and keeps view queries on a single shard.

References

• RFC 5545 — iCalendar core object specification
• RFC 5545 errata (incl. ID 4271 — DST-gap clarification)
• RFC 5546 — iTIP
• RFC 6047 — iMIP
• RFC 4791 — CalDAV
• RFC 6638 — Scheduling extensions to CalDAV
• RFC 6578 — WebDAV collection synchronization
• RFC 7809 — CalDAV time zones by reference
• RFC 7986 — New properties for iCalendar (NAME, COLOR, IMAGE, REFRESH-INTERVAL, SOURCE, CONFERENCE)
• IANA Time Zone Database
• Google Calendar API — Synchronize resources efficiently
• Google Calendar API — Push notifications (watch channels)
• Google Calendar API — Recurring events
• Google Calendar API — Events resource reference
• rrule.js