0010 — Google Workspace integration: view, never own

• Status: accepted
• Date: 2026-05-06
• Deciders: Derek

Context

Small NFPs and arts organizations almost universally use Google Workspace — Gmail, Calendar, Drive, Docs, Sheets. Ark is positioned as the cohesive platform that the org owns, but trying to also replace Google Workspace is a different — much larger — project.

The competing pull is clear: a tenant who logs into ark wants to see their team’s calendar, find the project document, book a meeting that respects existing availability. They don’t necessarily want a new place to author documents.

Decision

Ark integrates with Google Workspace as a viewer and linker. The data stays in Google.

Concretely:

• Calendar. OAuth read-only access (calendar.readonly initially). Ark surfaces availability and upcoming events in-context. The events themselves are queried at render time with a thin cache; we don’t replicate Google’s calendar database.
• Drive / Docs / Sheets. Ark stores file references — id, title, last-modified timestamp, share URL — not file contents. Embeds use Google’s standard viewer iframes. Editing happens on Google.
• Gmail. Out of scope. Privacy and compliance overhead exceed the value of a unified inbox view.

What ark continues to own (because office formats aren’t the right shape for these):

• Forum threads, replies, mentions
• Wiki pages (Markdown — Google Docs isn’t good at “small reference doc”)
• CMS entries (schema-driven content types)
• Permissions, audit logs, scheduling
• Anything purpose-built that Google has no native equivalent for

Consequences

Easier:

• Ark’s data inventory is small. The “what does ark store about us?” transparency dashboard (per ADR 0008) shows a short list.
• Onboarding a new tenant doesn’t require document migration — point ark at their existing Google Workspace and the documents are already there.
• Ark is never the source of truth for a Google Doc. No collaboration-conflict resolution problems.
• Smaller surface for security/compliance review.

Harder:

• Tenants without Google Workspace lose substantial functionality. (The mitigation: most tenants we’re targeting use it. We can add a Microsoft 365 adapter later if a tenant needs it; same architectural pattern.)
• We depend on Google’s API stability — but this is a known, well-supported set of APIs.
• Some friction at the seam: a forum thread might reference a Doc by URL; the Doc’s title changes in Google; ark needs a sync strategy. Acceptable; small.

Revisit if:

• Multiple target tenants are not on Google Workspace and need ark to be the document home
• Google materially changes the API model for embedded viewing or OAuth scopes

OAuth scope strategy

Start narrow. Add scopes only with a clear feature behind each:

• calendar.readonly — calendar view, availability for scheduling
• drive.metadata.readonly — list and search files referenced in ark
• drive.file (per-file consent) — open specific docs in embedded viewer

Avoid gmail.* and drive (full). Tenant trust is asymmetric — we earn it back slowly if we ask too broadly up front.

Alternatives considered

• Replicate Google data into ark. Owning copies of Calendar events / Drive metadata. Loses transparency advantage and creates sync hell. Rejected.
• Skip integration entirely; let users keep tabs open. Sometimes correct, but tenants are paying for the cohesive view. Skipping integration would lose the cohesion.
• Build our own docs/sheets/calendar. Decade-long effort to match Google’s quality. Out of scope.
• Microsoft 365 first. Considered. Most target tenants are on Google. Architecture is provider-pluggable; adapter could come later.