• Impact of errors is worse than impact of failures: if an event silently “forks” (two times/guest lists both accepted), you get double-bookings and missed meetings. That feels like data corruption and destroys trust in the calendar. A transient “failed to save, please retry” is annoying but recoverable.
• Partitions are rare, events are core: DB/quorum partitions are exceptional; event correctness is exercised constantly. Optimizing for the rare case (AP) at the cost of everyday correctness (C) is the wrong trade here.
• Our other features depend on a single truth: free/busy computation, time suggestions, and multi-device sync all assume one canonical version of each event. If we allowed divergent writes, we'd need complex reconciliation logic that leaks into RSVP state, availability results, and device views.
• Offline is handled at the edge, not by weakening server guarantees: when a user is offline, we queue changes locally and reconcile on reconnect with version checks. We do not relax the server’s consistency just because clients may be disconnected; this keeps the core store clean and predictable.

In most ShowOffer delivery frameworks, we walk each FR vertically (FR → APIs → Entities → Workflow → Diagram). For this calendar system, I’ve intentionally pulled APIs and Entities into shared sections instead of repeating them inside each FR.

There are two main reasons:

1. Heavy cross-FR reuse of the same entities and APIs
   In this problem, almost all FRs depend on the same core objects: Event, EventException, Invitation, FreeBusyBlock, and ChangeLog. The same APIs (e.g., GET /v1/events, GET /v1/events?start_ts=…, POST /v1/freebusy) are used by multiple FRs: FR1 for CRUD, FR3 for views, FR4 for free/busy. If we followed the standard per-FR layout, we’d either duplicate these definitions four times or constantly say “same as FR1,” which adds noise but no insight.
2. Entities evolve as later FRs are introduced
   The data model for a calendar is central and grows over time: FR1 defines Event and EventException, FR2 adds Invitation, FR4 adds FreeBusyBlock, and all of them write to ChangeLog. If entity tables lived inside each FR section, every refinement (e.g., adding rsvp_status or changing recurrence_rule) would require editing multiple places, increasing the risk of inconsistent diagrams and descriptions. A single Core Data Model section keeps entities canonical and lets FR sections focus on how they use those entities, not re-explain what they are.

Practically, this structure is still interview-friendly: verbally, I can walk each FR vertically (APIs → key entities → workflow), but in the written version I centralize APIs and Entities to avoid duplication and make it easier for the interviewer to see the big picture of the system at a glance.

Semantically it’s a read, so we could expose GET /v1/availability with query params, but in practice we’d use POST because the request shape (multiple users, time windows, optional constraints) fits a JSON body much better and avoids URL length / encoding headaches.

When a recurring event is created, immediately generate one row per occurrence for some horizon, e.g.:

• On create: write all occurrences for the next 12 months into Event (or an EventInstance) table.
• A background job periodically extends the horizon (e.g., always keep “next 6–12 months” materialized).
• “This instance only” edits just update that one row.

Example:

If you create a weekly standup starting Jan 6, 2025:

• You insert ~52 rows (one per week) covering Jan 2025–Jan 2026.
• For FR3 & FR4 just query these instance rows by time range.

Pros

• Very simple reads for FR3/FR4:
  • Views and availability are just “give me events in [start_ts, end_ts]”.
  • No recurrence expansion logic on the critical read path.
• Simple per-occurrence edits:
  • “This instance only” = update that row.
  • “Cancel this instance” = mark that row cancelled.
• Debuggable: What you see in DB is close to what users see in UI (one row per actual calendar cell).

Cons

• Write amplification & storage blow-up:
  • Long-running series + many users = lots of rows.
  • Every “forever” series becomes N rows/year/user.
• Painful pattern changes (“this and future”):
  • You may need to update or delete many instance rows (potentially thousands) to reflect series changes.
  • Increases lock time and risk of conflicts.
• Horizon edge cases:
  • Beyond 1 year, the series “disappears” unless you pre-extend the horizon.
  • Background job failures → future meetings not visible.

In short, this option is great for very simple systems or short-lived recurrences, but doesn’t scale nicely for “forever” series and complex edits. Not a good fit for a Google Calendar–like product at tens of millions of users.

During the creation, store only the series definition and expand on read:

• Event entity has start_ts, timezone, recurrence_rule.
• FR3/FR4 always compute occurrences on-the-fly inside the requested window.
• There is no per-occurrence state as exception.

To keep this option coherent, we’d relax the product a bit:

• Only support series-level edits (scope=series).
• “This instance only” and “this and future” are not supported, or are internally treated as “change the whole series”.

Pros

• Simplest data model:
  • Just one Event row for the series; no exceptions, no extra tables.
• Writes are cheap:
  • Changing a series = update a single row.
• Reads are predictable:
  • Expansion cost depends on the window size, not on how many exceptions exist.

Cons

• Does not meet our product FR1:
  • We already committed to scope=single|this_and_future|series.
  • Users expect “just this instance” and “this and future” like Google Calendar.
• No true historical preservation:
  • If you change the series, you change the interpretation of past occurrences as well.
  • That breaks “don’t mutate history” and makes auditing messy.
• User-surprising behavior:
  • “I just wanted to move next week’s standup, but all past ones now look like they were at that new time.”

Overall, this is a nice “teaching” design for a simpler product, but it cannot satisfy our FR1 requirements (single-instance edits, this-and-future semantics, preserving history). We discard it given our spec.

The core idea is that we need to introduce an exception entity to deal with changes based on the defined event series initially:

• Event row = series definition (base start time + recurrence_rule).
• EventException rows = overrides or cancellations for specific occurrences, identified by event_id + original_start_ts.

On read (FR3/FR4):

• Expand series occurrences within the window.
• For each occurrence, look up a matching exception:
  • status = CANCELLED → drop it.
  • Otherwise, override fields (start_ts, end_ts, title, etc.) from the exception.

On write (FR1):

• scope=series → update the Event row.
• scope=single → insert/update a single EventException.
• scope=this_and_future → typically split series into old + new, plus a few exceptions if needed.

Pros

• Supports full product semantics:
  • “This instance only”, “this and future”, “series”.
  • Can move/cancel a single occurrence without rewriting everything.
• Preserves history:
  • Past occurrences remain interpretable using the original rule + exceptions.
  • Middle edits don’t rewrite past rows.
• Storage-efficient:
  • One row per series + one row per overridden occurrence; unchanged instances don’t consume more space.
• Good for reads with bounded windows:
  • Expansion is limited to the requested [start_ts, end_ts].
  • Exceptions are typically sparse, so per-window cost is reasonable.
• Aligns with Consistency:
  • Small, well-scoped writes (one series row + one exception row).
  • Easy to keep strong consistency with version on series and transactional updates including exceptions.

Cons

• More complex logic than previous 2 Options:
  • You need a recurrence engine and an “apply exceptions” step.
  • FR1 edits must carefully write both Event and EventException in one transaction.
• Slightly heavier reads than Option 1:
  • Need to: expand series → join with exceptions → apply overrides.
  • Needs thoughtful indexing and careful window limits to meet latency SLOs.
• Edge cases (e.g. “this and future” splits) require careful design:
  • You’ll need clear rules on when to split series vs when to add exceptions.

Overall, option 3 hits the best balance for a Google Calendar–like system:

• Meets our functional requirements (scope variants).
• Respects strong consistency + history preservation.
• Scales better than fully materialized instances (Option 1).
• More complex than Option 2, but the complexity is localized to:
  • Event + EventException data model, and
  • a clear “expand + override” algorithm.

This is the design we choose for the rest of DD1 and the overall system.

We have discussed option 3 that can solve the following use cases

• “This instance only” edits without breaking the whole series
• Mid-series changes without altering history
• One-off cancellations for individual instances
• Handling no-expiry / long-running series without infinite rows

So far, EventException handles sparse, one-off changes (“this instance only”). For larger pattern changes (“this and future”), we combine series split + exceptions.

Let’s look at a scenario to walk through how it builds the solution:

• Original series:
  • Title: “Team Sync”
  • Rule: every Monday 09:00–09:30, starting 2025‑01‑06, no end date.
  • Stored as one Event row: evt_123 with recurrence_rule="FREQ=WEEKLY;BYDAY=MO"
• On 2025‑03‑10, the user chooses in UI:
  “Edit → This and future” → move to 10:00–10:30

First, what do we do on Write?

Step 1 - Find the cut occurrence

• Compute the occurrence being edited:
  • Original instance start: 2025-03-10T09:00 in America/Los_Angeles → 2025-03-10T17:00:00Z.
  • This is the first occurrence that should follow the new pattern.

Step 2 - Truncate the original series (evt_123)

• Update evt_123’s recurrence to stop before the cut:
  • Add an UNTIL or equivalent limit so the last occurrence is 2025‑03‑03.
  • All history up to (and including) 2025‑03‑03 stays governed by this row.

Step 3 - Create a new series starting at the cut (evt_456)

• Insert a new Event row:

| Field         | Value                                        |
|---------------|----------------------------------------------|
| `event_id`    | `evt_456`                                    |
| `start_ts`    | `2025‑03‑10T18:00:00Z` (10:00 local)         |
| `end_ts`      | `2025‑03‑10T18:30:00Z`                        |
| `timezone`    | `America/Los_Angeles`                        |
| `recurrence_rule` | `FREQ=WEEKLY;BYDAY=MO` (same weekly rule)|
| `status`      | `ACTIVE`                                     |
| `version`     | `1`                                          |
    

• Copy over other fields (title, description, location, organizer, etc.).
• If there are invitations (FR2), we also clone the guest list from evt_123 to evt_456.

Step 4 - No exceptions needed in this simple case

• Because the change applies cleanly at a boundary (“this date and all future”), we don’t need EventException for this example.
• For more complex changes (e.g., shifting days with overlapping patterns), we might still use a small number of exceptions around the split.

2. How reads behave after the split?

• Past weeks (before 2025‑03‑10):
  • FR3/FR4 expansion sees only evt_123, whose recurrence now ends before the cut.
  • All those occurrences remain at 09:00–09:30.
• From 2025‑03‑10 onward:
  • Expansion sees evt_456 starting on 2025‑03‑10 at 10:00–10:30 and weekly afterwards.
  • The calendar shows the new time from that date forward.

Each device periodically polls:

• Either GET /v1/events?start_ts&end_ts for the visible window, or
• A light /v1/sync endpoint with “changes since X”.

Polling interval might be 10–30 seconds.

Pros

• Very simple to implement:
  • No extra infra beyond existing APIs.
  • No WebSockets / push infra.
• Fully leverages strong server state:
  • Every poll gets canonical data from the DB.

Cons

• Latency tied to the polling interval:
  • If we poll every 30 seconds, worst-case propagation is ~30s.
  • To reach 3–5s, we’d need very aggressive polling → lots of wasted traffic.
• Expensive at scale:
  • Tens of millions of users × frequent polls = massive QPS, most of which return “no changes”.
• Battery / bandwidth unfriendly on mobile.

Summary
Good as a baseline and fallback, but doesn’t hit our latency + efficiency goals cleanly.
We’ll keep a slow poll as a safety net, but not rely on it as the primary mechanism.

Improve Option 1 by adding a change log and a delta API:

• Maintain a ChangeLog (or EventChange) table with a monotonically increasing sequence.
• Expose a GET /v1/sync?cursor=...:
  • Input: last seen cursor.
  • Output: list of changes since that cursor (create/update/delete, event_ids) + new cursor.
• Devices poll /sync periodically instead of refetching full views.

Pros

• Much cheaper than refetching everything:
  • Devices only pull changes, not full windows.
• Good offline story:
  • When a device comes back, it calls /sync with its last cursor and gets all missed changes.
• Still uses strong server state as source of truth.

Cons

• Still limited by polling interval:
  • If /sync is polled every 15–30s, multi-device lag is still too high.
• Extra complexity on the backend:
  • Need to maintain ChangeLog and cursors.
• Doesn’t exploit the fact that many devices are online and connected and could be notified immediately.

Summary
Better than pure polling and useful as a core primitive (we’ll reuse /sync), but not enough on its own to reach “near real-time” without aggressive polling.

Now how about we combine:

• A ChangeLog + /sync API (Option 2), and
• A push-based invalidation channel

So the flow looks like:

1. When Calendar Service commits a change, it writes to ChangeLog and publishes a “user X has updates” message.
2. Online devices for that user maintain a push connection (WebSocket / SSE / mobile push).
3. When they receive an invalidation (“there are changes after cursor K”), they immediately call /v1/sync?cursor=K to pull the actual deltas.
4. Offline devices simply call /v1/sync when they come back.

Pros

• Near real-time for online devices:
  • Push invalidation reaches the device quickly; the only latency is one /sync call.
• Efficient:
  • Push payloads are tiny (“you have changes”), data comes from /sync which only returns deltas.
• Great offline story:
  • When offline, device misses pushes but can catch up using /sync and its cursor.
• Aligns with strong consistency:
  • Server is the canonical state; push is just a trigger, not data truth.

Cons

• More infra:
  • Need a Notification/Sync Service (or reuse an existing one).
  • Require a durable message channel (e.g., Kafka / PubSub) between Calendar Service and Notification Service.
• More moving parts:
  • Need to handle dropped connections, reconnects, and push failures gracefully.

Summary
Option 3 best matches our NFR2 (multi-device real-time) + NFR3 (scalability):

• Use /sync + ChangeLog as the core abstraction.
• Layer push invalidation on top to get <5s propagation for online devices.
• Fall back to periodic polling /sync for robustness.

We’ll adopt Option 3.

Let’s say a user on Laptop edits an event time; Phone and Tablet should update.

1. Laptop → API-GW → Calendar Service
   • PATCH /v1/events/{event_id} with new time, version, scope, etc.
   • Calendar Service validates, applies business logic, writes to Event (+ EventException / Invitation if needed) in a single transaction.
2. Calendar Service writes ChangeLog
   • After the transaction commits, for each affected user (organizer + invitees):
   • Insert into ChangeLog:

   (change_id = NEXTVAL,
    user_id = guest_or_organizer,
    event_id = evt_123,
    change_type = UPDATED,
    changed_at = now)
           

   • For each inserted row, publish a message to the message bus or directly to Notification Service:

   { "user_id": ..., "latest_change_id": ... }
           

3. Notification / Sync Service pushes invalidation
   • Receives the message and looks up active connections for that user_id (Laptop, Phone, Tablet).
   • Sends a small push: “Your calendar has changed; latest cursor ≥ 12360”.
4. Other devices call /sync
   • Phone and Tablet receive the push.
   • Each calls: GET /v1/sync?cursor=their_last_seen_cursor.
   • Calendar Service:
     • Reads ChangeLog rows for that user_id with change_id > cursor.
     • Returns a list of changes (and optionally the updated event docs).
   • Devices update their local view/cache.

Propagation time is dominated by:

• Calendar write latency + ChangeLog insert,
• Message bus + push latency,
• One /sync call.

This keeps us well within the 3–5s p95 target.

In this deep dive, we want to:

• Quickly check a group of users’ availability/conflicts in < 500 ms p95 over a 1–2 week window for interactive “find a time” flows.
• Find a suggested time from the system based on availability checks.

Recall from HLD that POST /v1/availability currently walks Event + Invitation, uses the Recurrence Engine from DD1, and computes busy intervals online.

In the entities section, we marked FreeBusyBlock as optional. In this deep dive we’ll explore whether we actually need such a derived store, and if so, how to keep it fresh while preserving our Consistency over Availability stance.

For each check with /v1/availability request:

1. For each target user:
   • Query Event + Invitation overlapping [start_ts, end_ts].
   • Use the Recurrence Engine to expand recurring series in that window and apply EventException.
   • Merge instances into busy intervals in memory.
2. Return per-user busy blocks; suggestions (if any) are computed by intersecting these blocks on the fly.

Pros

• Simple & fully consistent:
  Always reflects current Event + EventException + Invitation state.
• No extra storage beyond existing tables.
• Easy to reason about correctness (only one source of truth).

Cons

• CPU & DB heavy:
  • Same recurrence expansion work is redone on each call.
  • Availability for the same people/window is recomputed again and again.
• Latency grows with:
  • Number of events in the window,
  • Complexity of recurrence rules,
  • Number of attendees.
• Hard to guarantee < 500 ms p95 at high scale and during peak times.

Summary
Great as a baseline and fallback, but too expensive to be the hot path for a large calendar product.

Predefined in offline jobs, we can:

• Run a periodic batch (e.g., nightly or hourly) that:
  • Expands events for each user for the next N days (say 30–60).
  • Materializes per-user busy intervals into a FreeBusyBlock table.
• /v1/availability queries FreeBusyBlock instead of raw events.

Pros

• Very fast reads:
  • Availability queries become simple range scans over pre-merged blocks.
• Easy to compute suggestions:
  • Work on a small set of intervals instead of all events & recurrences.

Cons

• Staleness:
  • Any event changes after the batch won’t show in free/busy until the next run.
• Tradeoff is unpleasant:
  • Either accept noticeably stale answers (“this time looks free but was just booked”),
  • Or add real-time corrections on top, which complicates the system anyway.
• Batch cost grows with user base; recomputing everything each run can be expensive.

Summary
Nice for a small or low-change system, but the staleness is too high for a Google-Calendar–like product that expects near real-time availability.

Use a derived “busy blocks” store per user that is:

• Incrementally updated when events change, driven by the same ChangeLog/Kafka pipeline from DD2.
• Backed by the Recurrence Engine from DD1 to recompute only the affected days.
• Served via a cache (e.g., Redis) so /v1/availability reads are fast and predictable.

The canonical truth is still Event + EventException + Invitation; FreeBusyBlock is a materialized view tuned for FR4.

We keep Option 1 as a fallback (misses, edge cases), but most requests hit the derived store.

1. Client → API-GW (FR1/FR2 write)
   • User creates/updates/deletes an event or RSVP.
   • Client calls one of the existing APIs:

   POST   /v1/events
   PATCH  /v1/events/{event_id}
   DELETE /v1/events/{event_id}
   PATCH  /v1/events/{event_id}/rsvp

2. API-GW → Calendar Service
   • API-GW authenticates the request, extracts user_id, and forwards it.
3. Calendar Service → Apply core business logic (canonical write)
   • Validates payload, permissions, and recurrence (from DD1).
   • Applies FR1/FR2 logic in a strong-consistency transaction to tables:
     • Event, EventException, Invitation, and optionally Calendar.
4. Calendar Service → Append ChangeLog rows (DD2)
   • After transaction commits, for each affected user (organizer + invitees):

   Insert into ChangeLog:
   {
     change_id,
     user_id,
     event_id,
     change_type,
     changed_at
   }

5. Calendar Service → Kafka (user updates topic)
   • For each ChangeLog row, publish a small message:

   {"user_id": "u123", "event_id": "evt_456", "change_type": "UPDATED"}

   • Topic is partitioned by user_id.
6. FreeBusy Updater Worker ← Kafka (DD3)
   • Subscribes to the user-updates topic.
   • For each message:
   • a. Find affected days: Look up events to find impacted calendar days.
   • b. Rebuild FreeBusy for (user_id, day):
     • Query: Event, EventException, Invitation
     • Use recurrence engine to expand, filter for visible attendees, and merge blocks.
   • c. Write FreeBusyBlock:
     • Delete existing rows for (user_id, D).
     • Insert merged rows + set last_rebuilt_at.
7. FreeBusy Updater → FreeBusyCache (optional)
   • If (user_id, day) is in the configured “hot window” (e.g. next 4 weeks):
   • Update/invalidate corresponding entry in FreeBusyCache (Redis / in-memory).
   • Keeps FreeBusyBlock + cache aligned with canonical change.
8. End State
   • Canonical tables remain source of truth.
   • FreeBusyBlock (and optionally cache) are up-to-date, ready for /v1/availability.

1. Client → API-GW (POST /v1/availability)
   • Organizer opens “Find a time” and selects attendees + a date range (e.g., next 2 weeks).
   • Client calls:

   {
     "user_ids": ["u1", "u2", "u3"],
     "start_ts": "...",
     "end_ts": "..."
   }

   • Request is authenticated at API-GW and forwarded to Calendar Service.
2. Calendar Service → Normalize request window
   • Validates start_ts < end_ts and window length limits.
   • Computes the set of calendar days D that intersect [start_ts, end_ts].
3. Calendar Service → FreeBusyCache (fast path)
   • For each requested user_id:
   • For each day d ∈ D:
     • Tries to read busy blocks from FreeBusyCache (e.g., key like freebusys:{user_id}:{day}).
4. Cache miss → DB (FreeBusyBlock)
   • For (user_id, d) entries missing in cache:
     • Query FreeBusyBlock rows from the DB for that user and day.
     • Populate cache entries with a short TTL (e.g., a few minutes), so subsequent requests are fast.
5. Merge & trim per user
   • For each user:
   • Combine all their busy blocks across days in D.
   • Re-merge if needed and trim intervals to the exact [start_ts, end_ts] window.
   • Prepare a per-user list:

   {
     "user_id": "u1",
     "busys": [
       { "start_ts": "...", "end_ts": "..." },
       ...
     ]
   }

6. (Optional) Fallback on-the-fly for gaps
   • In rare cases where FreeBusyBlock doesn’t exist yet for a (user_id, day):
     • Compute free/busy on-the-fly from canonical Event + EventException + Invitation.
     • Optionally backfill FreeBusyBlock and cache that day.
7. Meeting suggestions (if needed)
   • Calendar Service can:
   • Derive free intervals per user inside [start_ts, end_ts].
   • Intersect across attendees to find candidate slots.
   • Return raw busy data and suggestions.
8. Response → Client
   • Calendar Service returns a JSON payload like:

   {
     "users": [
       { "user_id": "u1", "busys": [ ... ] },
       { "user_id": "u2", "busys": [ ... ] }
     ],
     "suggested_slots": [
       { "start_ts": "...", "end_ts": "..." },
       ...
     ]
   }

   • Client renders colored free/busy strips and time suggestions.