ihnyc-rc-cal-landing Google OAuth (dev)

This document describes a proposed Google OAuth-based auto-sync flow for the IHNYC RC Calendar service. This is a development-only plan and not in production.

Why OAuth

• The current Google “Add” link uses the web subscription flow and is unreliable on mobile.
• Google Calendar rejects malformed ICS (RFC5545) and does not offer a native app deep link for subscriptions.
• OAuth + Calendar API enables reliable, automated syncing by writing events directly into a user’s Google Calendar.

Current Flow (web subscription)

sequenceDiagram
  autonumber
  participant U as User (mobile/desktop)
  participant W as IHNYC RC Subscribe Page
  participant G as Google Calendar Web
  participant I as IHNYC ICS Feed

  U->>W: Click "Add to Google"
  W->>G: Open https://calendar.google.com/calendar/r?cid=<encoded URL>
  G->>U: Prompt sign-in (browser)
  G->>I: Fetch ICS (web subscription flow)
  I-->>G: ICS response (long lines can break)
  G-->>U: "Unable to add, check URL" (sometimes)

Proposed Flow (OAuth auto-sync)

sequenceDiagram
  autonumber
  participant U as User
  participant W as IHNYC RC Subscribe Page
  participant O as IHNYC OAuth Service
  participant G as Google OAuth
  participant C as Google Calendar API
  participant I as IHNYC ICS Feed
  participant S as Sync Worker

  U->>W: Click "Connect Google Calendar"
  W->>O: Start OAuth
  O->>G: Redirect to consent
  G-->>U: Google login + consent
  U->>G: Approve
  G->>O: OAuth callback (auth code)
  O->>G: Exchange code -> tokens
  G-->>O: access_token + refresh_token
  O->>C: Create dedicated calendar
  O-->>W: Success (calendar connected)

  S->>G: Refresh access token (using refresh_token)
  S->>I: Fetch ICS feed
  S->>C: Upsert events (UID mapping)
  S->>C: Delete removed events

Key Notes

• Dev-only: This is a plan/design doc, not deployed.
• The OAuth flow requires a Google Cloud project and consent screen.
• Refresh tokens must be stored securely and can be revoked by users.
• Auto-sync implies a server-side scheduler and event reconciliation logic.

Related Docs

• services/ihnyc-rc-cal-landing/integrations.md
• services/ihnyc-rc-cal-landing/architecture.md