google-calendar

Start with the simplest case: one user creates events and retrieves them by time range. No attendees, no notifications — just event storage and retrieval.

Event Service

A single stateless service handles all event operations. The client sends REST requests through an API Gateway, which authenticates the user (JWT) and forwards to the Event Service.

Authorization

The Event Service checks that the authenticated user owns the calendar before allowing any operation. This is a simple ownership check: calendar.owner_id == token.sub.

Indexed Range Queries

Calendar views always request events within a time window (a week, a month). The key query pattern is:

A composite index on (calendar_id, start_time) makes this query efficient — it narrows to the user's calendar first, then scans the time range.

✅ Works for: A single user managing their own calendar events

❌ Missing: No attendees — events are single-user only. No notifications. No RSVP. No way to invite others to a meeting.

A calendar without attendees is just a to-do list. Real value comes from multi-user events — invitations, RSVP tracking, and ensuring only valid attendees can respond.

The Attendees Join Table

Events and users have a many-to-many relationship. The attendees table captures this relationship with its own attribute — rsvp_status:

RSVP Validation

When an attendee RSVPs, the service must validate two things:

1. The user is actually in the attendee list (prevents unauthorized RSVP)
2. The new status is a valid transition (accepted, pending, or denied)

The RSVP flow:

1. Attendee sends POST /events/{id}/rsvp with their status
2. Event Service checks attendees table for (event_id, user_id) — if no row exists, reject with 403
3. Update rsvp_status in the attendees table

Transactional Integrity

Event creation with attendees must be atomic — if the attendee inserts fail (e.g., invalid user_id), the event insert must also roll back. This is a natural fit for a SQL transaction wrapping all inserts.

✅ NFRs addressed: Data integrity (transactional event+attendee creation), security (RSVP validation ensures only listed attendees can respond)

❌ Still missing: When an event is created or updated, attendees don't know about it. No notifications — the organizer could change the meeting time and attendees would never find out.

A calendar that doesn't remind you about meetings is barely better than a spreadsheet. Notifications transform it from a passive record into an active coordination tool. But notifications introduce asynchronous complexity: they must be scheduled for the future, survive service restarts, and handle failures gracefully.

Two Types of Notifications

1. Immediate: Event created/updated/cancelled → notify attendees now
2. Scheduled: Reminder 30 minutes before event start → deliver at start_time - 30min

The Pipeline

We decouple event mutations from notification delivery using a message queue:

1. Event Service writes the event to the database
2. After commit, it publishes an event-changed message to the queue
3. Notification Worker consumes the message and:
   • For immediate notifications: sends emails via the Email Service
   • For scheduled reminders: inserts rows into the notifications table with notify_at = event.start_time - 30min
4. A Scheduler periodically polls the notifications table for rows where notify_at <= now() AND sent = false
5. The Scheduler dispatches emails via the Email Service and marks rows as sent = true

Why a Message Queue?

If the Event Service called the Email Service directly, a failed email would block the event creation response. The message queue decouples the write path from the notification path:

• Event creation always succeeds quickly (synchronous DB write)
• Notification delivery is retried independently (at-least-once via queue)
• If the notification worker is down, messages accumulate in the queue and are processed when it recovers

Handling Event Updates

When an event's time changes, existing notification rows become invalid. The Notification Worker must:

1. Delete old unsent notification rows for that event
2. Insert new rows with the updated notify_at time

This is an idempotent operation — processing the same event-changed message twice produces the same result.

Failure Handling

• Email delivery failure: Retry 3 times with exponential backoff. After 3 failures, move to a Dead Letter Queue (DLQ) for manual review.
• Scheduler crash: On restart, it simply polls notify_at <= now() AND sent = false — unprocessed rows are picked up. No state is lost.
• Duplicate notifications: The sent flag prevents re-sending. The Scheduler uses UPDATE ... WHERE sent = false RETURNING * to atomically claim rows.

✅ NFRs addressed: Notification reliability (at-least-once delivery via queue + DLQ), availability (async pipeline doesn't block event writes)

❌ Still missing: No support for recurring events — a user can't create "Team standup every Monday at 9am" without creating 52 separate events. No concurrent modification handling.

Recurring events are by far the most complex feature in any calendar system. A simple "weekly standup" generates potentially infinite instances — you can't store them all. The system must generate instances on the fly while supporting exceptions ("skip next Monday" or "move this Friday's meeting to Thursday").

RRULE: The Industry Standard

We use the iCalendar RFC 5545 RRULE format — a well-defined standard with open-source libraries for parsing and expanding rules:

Querying: Two-Phase Approach

When a user requests events for a time range, we query two categories:

1. Non-recurring events — straightforward range query on start_time:

2. Recurring events — select all recurring series that started before the query end:

Then expand each recurring event in application code using an RRULE library (e.g., rrule.js) to generate instances within the requested range. Merge both result sets into a single list sorted by start_time.

Exceptions to Recurring Events

Users often modify or cancel individual instances ("move this Monday's standup to Tuesday"). We handle this with an exceptions table:

• Skip an instance: Insert an exception with replacement_event_id = NULL
• Modify an instance: Create a new standalone event and reference it as the replacement

During expansion, the service checks the exceptions table and substitutes or removes instances accordingly.

Notification Scheduling for Recurring Events

We can't pre-schedule notifications for all future instances (infinite series). Instead, a rolling window scheduler creates notification rows for the next 7 days. A daily cron job refreshes the window.

✅ NFRs addressed: Scalability (one DB row represents infinite instances), data integrity (exceptions cleanly override individual occurrences)

❌ Still missing: No conflict detection — two events can overlap without warning. No concurrent modification handling — two users editing the same event simultaneously can overwrite each other's changes.

The last pieces address event conflicts and concurrent modifications — features that make the calendar reliable enough for enterprise use.

Conflict Detection & Free/Busy Queries

Users need to see availability before scheduling. The system exposes a free/busy API that merges time ranges:

1. Fetch all accepted events for a user in a time range
2. Merge overlapping intervals (classic greedy algorithm)
3. Return busy blocks — other users see these as unavailable times

Conflict detection at event creation is a warning, not a block — Google Calendar allows double-booking but shows a visual warning.

Optimistic Locking for Concurrent Modifications

When multiple users can edit events (e.g., shared calendars in the future), concurrent modifications must not silently overwrite each other. We use optimistic locking with a version field:

If the version doesn't match, the update fails and the client receives a 409 Conflict response. The client fetches the latest state and asks the user to re-apply their changes — a reject-and-retry approach that's simple and effective for the low edit frequency of calendar events.

Caching Layer

Calendar views are read-heavy (10:1 read/write ratio). A Redis cache layer reduces database load:

• Cache key: calendar:{calendarId}:events:{weekStart} → list of events for that week
• Invalidation: On any event mutation, invalidate the cache entry for the affected calendar and time range
• TTL: 5 minutes — stale data window is short enough for a calendar app

NFR Scorecard

Recurring events are deceptively complex. A "weekly standup on Mondays" sounds simple, but consider: What if the user changes the name of just one instance? What if a holiday falls on Monday and they cancel that instance? What if they change the recurrence from weekly to biweekly — does that affect past instances?

Storage Strategies

We choose the hybrid approach: the recurring series is stored as a single row with an RRULE; exceptions (cancelled or modified instances) are materialized in a separate table.

The RRULE Expansion Pipeline

When expanding recurring events for a time range:

1. Parse the recurrence_rule string using an RFC 5545-compliant library
2. Generate all instance dates within [range_start, range_end]
3. Check the recurrence_exceptions table for this series:
   • If an instance date has a replacement_event_id → use the replacement
   • If an instance date has replacement_event_id = NULL → skip (cancelled)
4. For each surviving instance, clone the parent event's metadata (title, location, attendees) with the computed start/end time

The "This and All Future" Problem

When a user modifies "this and all future events", we split the series:

1. Update the original series' RRULE to end at the split date (UNTIL=...)
2. Create a new recurring event starting from the split date with the new properties

This avoids retroactively changing past instances while giving the user a clean new series going forward.

<discuss-with-ai-button title="Recurring Event Strategies" context="Google Calendar uses hybrid virtual expansion: one DB row per series with RRULE, materialized exceptions for modified/cancelled instances. 'This and all future' splits the series into two. Expansion happens in application code using RFC 5545 libraries." points='["How do you handle notification scheduling for events that repeat infinitely?","What happens if an attendee RSVPs to a specific instance of a recurring event — where is that stored?","How does timezone handling interact with recurring events — what if DST changes the wall-clock time?","What is the performance impact of expanding recurring events for a year view (52+ instances per series)?","How does Google Calendar handle 'every weekday' vs 'every Mon-Fri' when holidays are involved?"]'>

Finding free time slots is essentially the merge intervals problem from LeetCode, but applied at system design scale with real-world complications: recurring events, multiple attendees, and privacy constraints.

Overlap Detection

Two events overlap if one starts before the other ends:

If the count is > 0, there's a conflict. The system shows a warning but still allows creation — Google Calendar intentionally permits double-booking.

Free/Busy API

The free/busy endpoint returns merged busy blocks without exposing event details (privacy). Other users can see when someone is busy, but not why.

The Merge Intervals Algorithm

1. Fetch all accepted events for the user in the requested time range
2. Sort by start_time
3. Merge overlapping intervals:

Recurring Event Complication

Free/busy queries must expand recurring events within the requested range before running the merge algorithm. This means the computation is O(total instances in range), not O(stored events).

Performance Optimization

• Index: (user_id, start_time, end_time) on the attendees+events join for efficient conflict queries
• Caching: Cache free/busy results per user per day (invalidate on event mutation)
• Batch queries: For scheduling meetings with multiple attendees, run free/busy queries in parallel and intersect the results

When multiple users can edit the same event — e.g., shared calendars or delegated access — concurrent modifications can silently overwrite each other. This is a classic distributed systems problem.

The Problem

Alice and Bob both open the same event. Alice changes the title, Bob changes the location. If both save:

• Without protection: Last writer wins. Alice saves first → title=new, location=old. Bob saves second → title=old, location=new. Alice's title change is silently lost.
• With optimistic locking: Bob's save fails because the version changed. He's prompted to refresh and retry.

Approach Comparison

Our Choice: Optimistic locking. Calendar events are low-contention resources — the probability of two users editing the same event at the same second is low. When it does happen, the simple reject-and-retry UX is acceptable.

Implementation Details

1. Event record includes a version integer (starts at 1)
2. Client loads event and receives the current version
3. On save, the client sends version in the request body
4. Server performs: UPDATE events SET ... WHERE event_id = ? AND version = ?
5. If 0 rows affected → version mismatch → return 409 Conflict
6. Client shows a dialog: "This event was modified by someone else. Refresh to see the latest changes."

Notification Implications

If an event update is rejected due to a version conflict, no notification is triggered — the update never happened. This prevents spurious notifications from failed writes.

Sending 5,000+ notifications per second at exactly the right time is a distributed scheduling problem. The naive approach — a single cron job polling the database — breaks down when you need precision, reliability, and scalability.

The Naive Scheduler and Its Problems

A simple SELECT * FROM notifications WHERE notify_at <= now() AND sent = false running every minute works for small scale, but:

• Latency: Up to 60 seconds late (poll interval)
• Throughput: One query returns thousands of rows during peak hours
• Single point of failure: If the cron job crashes, all notifications stop

Partitioned Scheduler

Divide the notification table into time-based partitions. Multiple scheduler instances each claim a partition (e.g., by minute) using a distributed lock:

1. Scheduler instance claims partition for minute T (e.g., via Redlock)
2. Fetches all notifications where notify_at falls within minute T
3. Sends emails in batch via the Email Service
4. Marks all as sent = true
5. Releases the partition lock

Multiple instances can process different minutes in parallel, and no two instances process the same minute.

Exactly-Once Delivery

The combination of distributed lock + sent flag gives us effectively exactly-once delivery:

• The lock prevents two instances from claiming the same partition
• If an instance crashes mid-processing, the lock expires and another instance takes over — but only unsent rows are processed (checking sent = false)

Clock Skew Handling

Scheduler instances must agree on "now". If instance A's clock is 2 seconds ahead of instance B, they might both try to process the same minute. The distributed lock prevents this, but to avoid wasted work, instances use a shared time source (database server time via SELECT NOW() or a time service).

The following topics contain open-ended architectural questions for staff+ conversations.