System Requirements

Functional Requirements:

• Two-way sync with Google Calendar, Outlook, etc. (Read/Write events).
• Detect scheduling conflicts for multiple attendees.
• Automatically suggest alternative time slots if a conflict exists.
• Handle global time zone conversions seamlessly.
• Send asynchronous notifications for meeting updates/reminders.

Non-Functional Requirements:

• Accuracy: External calendar syncing must be highly reliable. A missed webhook from Google means a double-booked CEO.
• Low Latency for Suggestions: Calculating common free time for 10+ attendees must happen in < 300ms.
• Security: Securely store OAuth tokens for external calendar providers.

API Design

1. Schedule a Meeting POST /v1/events

JSON

2. Suggest Alternative Times POST /v1/events/suggestions

JSON

High-Level Design

• Client: Web/Mobile app, always rendering time in the user's local timezone.
• API Gateway: Handles routing and authentication.
• Scheduling Service: The core engine that calculates free time and detects conflicts.
• Calendar Sync Service: Manages OAuth tokens and interacts with Microsoft Graph API and Google Calendar API.
• Webhook Ingestion Service: Listens for push notifications from Google/Outlook when a user creates an event natively in those apps, updating your database to keep everything in sync.
• Primary Database (PostgreSQL): Stores users, OAuth credentials (encrypted), and local copies of Events.
• Message Broker (Kafka/RabbitMQ): Decouples the notification and syncing logic.

Detailed Component Design

Here is how we solve the heavy algorithmic lifting without pre-computing 90 days of slots.

1. Conflict Detection & Alternative Suggestions (The Algorithm)

When a user asks for a 60-minute slot for 5 attendees over a 5-day period, we treat this purely as an Interval Merging problem.

• Step 1: Query the database for all Events for those 5 users within the 5-day window. (e.g., SELECT * FROM Events WHERE userId IN (...) AND timeRange && [5-day-window]).
• Step 2: Merge overlapping intervals. If User A is busy from 1:00-2:30, and User B is busy from 2:00-3:00, the merged busy block is 1:00-3:00. This is done efficiently in memory using a sorted array and a sweep-line algorithm ($O(N \log N)$ time complexity).
• Step 3: Invert the merged busy blocks to find the "free blocks".
• Step 4: Filter the free blocks. If a free block is less than durationMinutes (60 mins), discard it. The remaining blocks are your perfectly calculated alternative suggestions.

2. Calendar Integration (Two-Way Sync)

Integrating with Google and Outlook is notoriously complex due to rate limits and pagination.

• Outbound (Writing): When a user creates a meeting via your API, the Calendar Sync Service puts a job on a message queue to call the Google/Outlook API asynchronously.
• Inbound (Reading): You register a Webhook URL with Google/Microsoft. When a user declines a meeting directly inside Outlook, Microsoft POSTs to your Webhook Ingestion Service. You drop this payload onto Kafka, and a consumer updates your PostgreSQL database to reflect the declined status.

3. The Time Zone Golden Rule

Time zones are the fastest way to introduce catastrophic bugs in a scheduling system. The architecture must enforce a strict boundary:

• The Backend: Knows absolutely nothing about local time zones. Every single timestamp in PostgreSQL, Kafka, and the APIs must be formatted as UTC (e.g., ISO 8601 Z).
• The Frontend: The client application detects the user's browser/device time zone and converts the UTC timestamps into local time purely for display purposes.