Google Calendar Sync - SH1SHANK/attendrix GitHub Wiki

📆 Google Calendar Sync – Documentation on System Architecture

📲 How to Subscribe to the Calendar?

Your class schedule is automatically synced to Google Calendar, making it easy to add to your personal calendar app. Choose the method that works best for your device:

📱 For iPhone / iPad (iCal)

The easiest way to add your class schedule to your iPhone or iPad is using the webcal:// subscription link:

  1. Open Safari on your iPhone or iPad
  2. Tap this link: 
    webcal://calendar.google.com/calendar/ical/8f6471671fa0ed8943250538ceedf97e5a8ce18b1ef09256738731bb37f57904@[email protected]/public/basic.ics
  3. Accept the prompt: "Would you like to subscribe to this calendar?"
  4. Done! Your class schedule now syncs automatically with the iOS Calendar app

🛈 Pro Tips:

  • You can rename the calendar in iOS Settings > Calendar > Accounts
  • To remove it later, go to Settings > Calendar > Accounts > Subscribed Calendars
  • The calendar will update automatically when your schedule changes

🤖 For Android / Google Calendar (Web/Desktop)

For Android devices or if you prefer using Google Calendar on the web:

  1. Tap this link or open it in Chrome: 
    https://calendar.google.com/calendar/u/0/r?cid=8f6471671fa0ed8943250538ceedf97e5a8ce18b1ef09256738731bb37f57904@[email protected]
  2. You'll see an "Add Calendar?" prompt in Google Calendar
  3. Click "Add" → Done! It syncs to your Google account across all devices

🛈 Browser Tips:

  • If it opens in Gmail or doesn't show the prompt, open Google Calendar manually and try the link again
  • The calendar will appear in your "Other calendars" section
  • You can change the calendar color and notification settings in Google Calendar

✅ You're All Set!

Your calendar is now subscribed and will stay up to date automatically. Whenever classes are added, updated, or cancelled, your personal calendar will reflect these changes within minutes.

🧠 How the Sync System Works (For Developers)

This section explains the technical architecture behind the automatic calendar synchronization system. The system ensures real-time updates between your class scheduling database and Google Calendar through a sophisticated serverless architecture.

🔹 Technologies Used

The sync system is built on a modern serverless stack:

  • Supabase - PostgreSQL database with real-time webhooks and Edge Functions
  • Google Calendar API - Direct calendar event management
  • Service Account Authentication - Secure server-to-server communication
  • Deno Runtime - TypeScript/JavaScript execution environment for Edge Functions

🔹 Step-by-Step Sync Flow

Here's how a class schedule change automatically appears in Google Calendar:

  1. Database Change → A class is added, updated, or deleted in the timetableRecords table
  2. Webhook Trigger → Supabase database webhook immediately fires
  3. Edge Function Execution → The webhook triggers the sync-calendar Edge Function
  4. Data Processing → Edge Function formats the class data for Google Calendar
  5. API Call → Direct call to Google Calendar API using service account
  6. Event Creation/Update → Google Calendar creates or updates the event
  7. ID Storage → The returned eventID is stored back in Supabase for future operations
graph LR
    A[Database Change] --> B[Webhook Trigger]
    B --> C[Edge Function]
    C --> D[Google Calendar API]
    D --> E[Event Created/Updated]
    E --> F[EventID Stored]

🔹 EventID Lifecycle Management

The system maintains a one-to-one relationship between database records and calendar events:

  • Creation: When a new class is added, a unique eventID is generated by Google Calendar
  • Storage: The eventID is stored in Supabase linked to the classID
  • Updates: Future changes to the class use the same eventID to update the existing calendar event
  • Deletion: When a class is removed, the eventID is used to delete the calendar event

This ensures no duplicate events and maintains data consistency across systems.

🔹 Create, Update, Delete Logic

The system handles all CRUD operations intelligently:

INSERT Operations:

  • New class records trigger event creation
  • Google Calendar returns a unique eventID
  • eventID is stored in the database for future reference

UPDATE Operations:

  • Uses stored eventID to update existing calendar events
  • Implements "upsert" logic - creates if event doesn't exist
  • Handles changes to time, venue, or course details

DELETE Operations:

  • Uses eventID to remove events from Google Calendar
  • Gracefully handles already-deleted events (404 errors)
  • Supports both direct deletion and old record cleanup

🔹 Error Handling & Resilience

The system includes robust error handling mechanisms:

Exponential Backoff Retry Logic:

  • Implements 2^attempt × 1000ms delay pattern
  • Retries failed API calls up to 3 times
  • Prevents cascade failures during Google API outages

Smart Error Classification:

  • Distinguishes between retryable and permanent errors
  • Logs detailed error information for debugging
  • Returns appropriate HTTP status codes

Time Zone Consistency:

  • All events use Asia/Kolkata timezone
  • Proper ISO datetime formatting
  • Handles daylight saving time transitions

🔹 Advanced Features

Multi-Calendar Support:

  • Routes events to appropriate calendars based on course type
  • Core courses → Batch-specific calendars
  • Elective courses → Course-specific calendars

Enhanced Event Properties:

  • Color coding for different class types (🔬 Labs vs regular classes)
  • Structured descriptions with course and class IDs
  • Automatic reminders (10 minutes popup, 30 minutes email)

Production Optimizations:

  • CORS handling for web application support
  • Input validation and sanitization
  • Comprehensive logging and monitoring

🔹 Calendar Resolution Logic

The system intelligently determines which calendar to use for each event:

// Simplified calendar resolution logic
if (courseType === "core" && batchID) {
  // Core courses go to batch-specific calendars
  calendarID = getBatchCalendar(batchID);
} else {
  // Elective courses go to course-specific calendars
  calendarID = getCourseCalendar(courseID);
}

🔗 Resources & References

📚 Technical Documentation

🔧 Implementation Guides

🛠️ Development Resources

📝 Note: This documentation covers the current system architecture. For specific implementation details or troubleshooting, refer to the linked resources or contact the development team.