Google Integrations

OAuth Connections

Google integration uses a provider-agnostic OAuth system:

• oauth_connections — Stores tokens per (teacherId, provider, providerAccountId)
• integration_settings — Stores typed JSONB config per (teacherId, integrationType)

Integration types: calendar_read, calendar_write, drive, meet

Use ConnectionService methods — never read/write tokens directly from the teachers table.

Google Calendar

Reading Availability

The Slot Engine uses Google Calendar’s freebusy.query API to check teacher availability:

1. Fetch selected calendars from integration_settings (calendar_read config)
2. Query FreeBusy API for the date range
3. Merge busy blocks with DB sessions
4. Remove overlapping slots

Writing Events

When sessions are confirmed, calendar events are created/updated:

Session confirmed → Create/update Google Calendar event
Session cancelled → Cancel calendar event
Session rescheduled → Update event time

Sync tracked in session_calendar_sync:

• syncStatus: synced / pending / failed
• googleCalendarEventId: event reference
• googleMeetLink: auto-generated Meet link

Note

Google Calendar is a sync target, NOT the source of truth. The database is always the primary source. Calendar events are side effects.

Calendar Sync Worker

A cron job (every 5 minutes) retries pending calendar sync operations:

• Batch of 20 records at a time
• Skips if google-calendar circuit breaker is open
• Automatic retry with backoff

Google Drive

Resource Integration

Teachers can add Drive files as resources via the file picker:

1. Teacher opens Drive file picker
2. Selects files to import as resources
3. Files tracked in teacher_resources (provider: ‘drive’)

Auto-Copy to Student Folders

When Drive resources are linked to a session, files are automatically copied to student folders:

1. Resource linked to session
2. DriveCopyService queues BullMQ job
3. Worker copies file to student's folder (students.driveFolderId)
4. Progress tracked in drive_file_copies table
   Status: pending → copying → copied / failed

Drive Sync Worker

Daily cron (3 AM) verifies Drive file integrity:

• Checks if files still exist in Drive
• Marks trashed/deleted files
• Reports inconsistencies

Circuit Breaker

Both Calendar and Drive API calls are protected by circuit breakers:

Service	Failure Threshold	Window	Recovery
Google Calendar	5 failures	60s	30s
Google Drive	5 failures	60s	60s

Only infrastructure errors (429, 5xx, timeouts) trip the circuit.

Calendar fallback: Sets syncStatus='pending', session creation never fails. Calendar-sync cron retries later.

Drive fallback: Workers skip and retry later via BullMQ DelayedError.

Rate Limiting

Redis-backed sliding-window rate limiting at two levels:

Service	Per-Teacher	Global
Google Calendar	10 req/10s	400/100s
Google Drive	5 req/10s	10,000/60s

Execution order: Circuit Breaker → Rate Limiter → Token refresh → API call → 429 Retry