← All decisions

Google Workspace integration: view, never own

accepted

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.