Calendar / Reminder Service — Detailed

flowchart TB
  subgraph Apps
    APP[Calendar app]
  end

  subgraph Edge
    GW
  end

  subgraph Cal[Calendar]
    CAL[Calendar Service]
    EVT[(Events DB)]
    RECUR[Recurrence expander - RFC 5545 RRULE]
    INV[Invitees + RSVPs]
    FREEBUSY[Free/busy lookup]
    OOO[Out-of-office]
  end

  subgraph Sched[Reminder scheduler]
    DELAYQ[[Delayed queue<br/>per-time bucket]]
    WHEEL[Hierarchical timing wheel]
    LEASE[Per-bucket lease]
    DEDUP[Idempotency keys]
  end

  subgraph Notif
    NS[Notification Service]
    PUSH((APNS / FCM))
    EMAIL
    SMS
  end

  subgraph Sync
    CALDAV[CalDAV / Google Calendar API]
    PUSH_CHN[Realtime change channel]
  end

  Apps --> Edge --> Cal
  Cal --> Sched --> Notif
  Sync --- Cal

    classDef client fill:#dbeafe,stroke:#1e40af,stroke-width:1px,color:#0f172a;
    classDef edge fill:#cffafe,stroke:#0e7490,stroke-width:1px,color:#0f172a;
    classDef service fill:#fef3c7,stroke:#92400e,stroke-width:1px,color:#0f172a;
    classDef datastore fill:#fee2e2,stroke:#991b1b,stroke-width:1px,color:#0f172a;
    classDef cache fill:#fed7aa,stroke:#9a3412,stroke-width:1px,color:#0f172a;
    classDef queue fill:#ede9fe,stroke:#5b21b6,stroke-width:1px,color:#0f172a;
    classDef compute fill:#d1fae5,stroke:#065f46,stroke-width:1px,color:#0f172a;
    classDef storage fill:#e5e7eb,stroke:#374151,stroke-width:1px,color:#0f172a;
    classDef external fill:#fce7f3,stroke:#9d174d,stroke-width:1px,color:#0f172a;
    classDef obs fill:#f3e8ff,stroke:#6b21a8,stroke-width:1px,color:#0f172a;
    class APP,CAL,RECUR,INV,FREEBUSY,OOO,WHEEL,DEDUP,NS,CALDAV,PUSH_CHN service;
    class EVT datastore;
    class DELAYQ queue;
    class LEASE storage;
    class PUSH external;

Recurrence

• RFC 5545 RRULEs (e.g., FREQ=WEEKLY;BYDAY=MO,WE).
• Expand on read or schedule per-occurrence ahead.
• Exceptions (deletes / modifications) stored separately.

Scheduler at scale

• Time-bucketed queue: per-minute buckets.
• Workers lease a bucket at minute boundary; dispatch.
• For high-volume reminders, timing wheel with O(1) ops.

Glossary & fundamentals

Concepts referenced in this design. Each row links to its canonical page; the tag column shows whether it is a high-level (HLD) or low-level (LLD) concept.

Tag	Concept	What it is	Page
HLD	Idempotency & retries	safe re-execution, backoff + jitter	idempotency-retries
LLD	REST API design	verbs, statuses, pagination, errors	rest-api-design
LLD	Async models	futures / async-await / coroutines / actors	async-models
LLD	Error handling	exceptions vs Result, error boundaries	error-handling