Skip to content

docs: add Google Sheets integration design catalog#397

Merged
BorisTyshkevich merged 18 commits into
mainfrom
docs/google-sheets-design
Jul 23, 2026
Merged

docs: add Google Sheets integration design catalog#397
BorisTyshkevich merged 18 commits into
mainfrom
docs/google-sheets-design

Conversation

@BorisTyshkevich

Copy link
Copy Markdown
Collaborator

Summary

Add a version-controlled design catalog for the browser-only Google Sheets integration.

The catalog defines:

  • product scope and ownership boundaries;
  • browser-only architecture and authentication;
  • versioned binding and checkpoint contracts;
  • managed spreadsheet layout;
  • snapshot export;
  • failure-safe full refresh;
  • ClickHouse 26.8+ append refresh using per-partition _block_number / _block_offset checkpoints;
  • large-result streaming and Google quota handling;
  • recovery, sharing, security, configuration, and testing;
  • accepted architecture decisions;
  • three self-contained HTML companion diagrams.

Key decisions

  • Repository design docs are the source of truth; issues are executable implementation slices.
  • Google never calls SQL Browser. Manual refresh launches the ClickHouse-hosted SPA through a hyperlink.
  • Bindings are append-only versions stored in a configured ClickHouse table.
  • Full refresh stages before publishing into the stable managed sheet ID.
  • Append refresh is available only for validated ClickHouse 26.8+ MergeTree-family sources.
  • Append uses finite queries and per-partition _block_number / _block_offset; SELECT ... STREAM, updates, and deletes are out of scope.
  • No silent truncation or silent fallback from append to full refresh.

Review entry point

docs/design/google-sheets/README.md

Scope

Documentation only. No runtime behavior changes.

@BorisTyshkevich
BorisTyshkevich merged commit e6ae34b into main Jul 23, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant