ADR-008: Google Calendar Integration — Automatic Event Creation on Poll Close

Date: 2026-04-11

Status: Accepted

Deciders: Platform Engineering Lead, Product

CODITECT Classification: Architecture Decision Record · A6

Context

v1.0 of the scheduling tool exports meeting times as static ICS files that participants must manually import into their calendars. This creates friction:

• Participants forget to import the ICS file
• The organizer must separately create a calendar invite and add attendees manually
• No Google Meet link is auto-generated
• There's no confirmation that attendees received the invite

The v2.0 requirement is: when the organizer closes a poll, automatically create a Google Calendar event, add all participants who provided their email, and let Google send invite emails.

Options evaluated:

Decision

Use Google Calendar API with a CODITECT service account impersonating 1@az1.ai via domain-wide delegation.

Architecture:

• Service account JSON key stored as GOOGLE_SERVICE_ACCOUNT_KEY Cloudflare Worker secret
• When organizer closes poll: Worker signs a JWT (RS256 via Web Crypto API), exchanges for access token, calls Calendar API
• Event created on the 1@az1.ai primary calendar with sendUpdates: "all" — Google sends invite emails to all attendees
• Google Meet link auto-generated via conferenceDataVersion: 1
• calendar_event_id and google_meet_link stored in polls table for reference
• Calendar event creation is non-blocking — if it fails, the poll still closes. Error logged.

Why service account (not OAuth):

• Zero friction for organizers — no OAuth consent screen
• Events come from a consistent CODITECT identity (1@az1.ai)
• Domain-wide delegation already available in CODITECT Google Workspace
• Matches the v1.0 philosophy: minimal friction for all users

Why JWT in Workers (not google-auth-library):

• Cloudflare Workers cannot use Node.js-dependent google-auth-library
• Web Crypto API supports RS256 signing natively
• JWT exchange is a single HTTP call to https://oauth2.googleapis.com/token

Consequences

Positive:

• Zero-click calendar integration — organizer closes poll, everyone gets an invite
• Google Meet link auto-generated — no separate setup needed
• Consistent sender identity (1@az1.ai) — professional branding
• Participants see the event in their Google/Outlook/Apple Calendar (Google invites are cross-platform)
• Contact data captured for CRM integration

Negative:

• Requires Google Workspace domain-wide delegation setup (one-time admin task)
• Service account key must be stored securely as Cloudflare secret
• Events are "owned" by 1@az1.ai — organizer doesn't see it in their personal calendar unless they're an attendee
• Participants without email don't get invites (email is optional)
• If Google Calendar API is down, event creation fails silently (logged, poll still closes)

Privacy:

• Participant email is stored in D1 only for the poll's lifetime (14-44 days, then purged)
• Email is only used for calendar invites — not marketing, not shared with third parties
• Privacy note shown in UI: "Only used for calendar invites. Never shared."
• Consistent with ADR-005 data retention policy

Alternatives Rejected

OAuth per-organizer: Each organizer would need to sign in with Google and grant calendar access. This contradicts the zero-friction design (v1.0 requires no accounts). Rejected.

Microsoft Graph: CODITECT uses Google Workspace internally. Supporting both Google and Microsoft would double the integration surface. Microsoft support deferred to v3.0 if needed.

CalDAV: Generic protocol but no standard invite mechanism. Would require building email sending separately. More complex with less functionality. Rejected.

Enhanced ICS with mailto: Could embed mailto: attendees in the ICS file, but the organizer would still need to send the file. Doesn't solve the automation problem. Rejected.

Review Trigger

Revisit when: (1) CODITECT supports Microsoft 365 customers who need Outlook calendar integration, (2) event volume exceeds Google Calendar API quotas (currently 1M events/day), or (3) CODITECT moves away from Google Workspace.