How richardx366/obsidian-google-drive works
1. What this repository is
- This is an Obsidian plugin that syncs a vault with Google Drive.
- The runtime boundary is the Obsidian app on the user’s device; the plugin runs inside Obsidian and manipulates the vault through Obsidian’s plugin API, not by directly acting as a separate desktop service.
2. Top-level architecture
- main.ts is the plugin entrypoint and orchestration layer.
- The sync logic is split into small helpers under helpers/, which suggests a command-driven architecture rather than a large monolith.
- pull.ts, push.ts, and reset.ts represent the three main synchronization modes exposed to the user.
3. Local subsystem: Obsidian vault + plugin state
- The plugin’s primary local boundary is the vault filesystem managed by Obsidian.
- It likely watches/reads local files through Obsidian APIs and converts them into sync operations.
- The README makes clear that file changes made outside Obsidian are intentionally out of scope; this is a key architectural constraint because the plugin depends on Obsidian’s change tracking.
4. Remote subsystem: Google Drive
- Google Drive is the canonical remote storage for synced vault content.
- The plugin creates a Drive folder per vault and uses Drive metadata/properties to associate files with the correct vault.
- The multi-vault design is based on vault-name identity, not a single global account-wide sync bucket.
5. Authentication and token boundary
- The plugin does not appear to do a direct Google OAuth flow inside Obsidian.
- Instead, the README indicates it uses https://ogd.richardxiong.com to convert a refresh token into an access token, explicitly to hide the client secret.
- That service is also used for a connectivity ping, so it is part auth broker, part availability check.
6. Sync flow: pull first, then push
- The main operational flow is: pull changes from Google Drive, then push local changes.
- This ordering is important because the README says push commands first pull, then upload.
- The sync engine therefore behaves like a reconciliation pipeline, not a pure upload tool.
7. Conflict handling and data precedence
- The plugin’s conflict policy is intentionally simple: local file priority with automatic resolution.
- The README notes one special case: cloud-side creation/modification can overwrite a local deletion.
- That means the architecture favors deterministic reconciliation over manual conflict UI or merge tooling.
8. Reset / state alignment
- reset.ts implies a destructive or re-baselining path used to make the local vault match Drive state.
- This is a separate subsystem from incremental sync, useful when the local vault must be treated as a mirror of remote state.
- In an architecture diagram, this is the “state reset” edge case, distinct from routine push/pull.
9. HTTP and API client layer
- helpers/ky.ts is likely a shared HTTP client wrapper, probably built around the ky library.
- helpers/drive.ts likely centralizes Google Drive API operations and abstract Drive file/folder representation.
- This separation matters because it isolates transport concerns from sync logic.
10. User-facing commands and interaction points
- The README references a ribbon button and command palette commands:
- Pull from Google Drive
- Push to Google Drive
- Set Local Vault to Google Drive
- These are user-triggered entry points into the same underlying sync engine, so the diagram should show multiple UI triggers converging into shared synchronization logic.
11. Build/release and package structure
- esbuild.config.mjs indicates the plugin is bundled for distribution with esbuild.
- manifest.json and versions.json are Obsidian plugin packaging/version compatibility metadata.
- .github/workflows/release.yml and version-bump.mjs show an automated release pipeline, so there is a build-and-publish boundary separate from runtime sync behavior.
12. What to emphasize in an architecture diagram
- Show three major zones:
- Obsidian local vault/plugin runtime
- Google Drive API
- ogd.richardxiong.com token broker / connectivity service
- Then connect them through:
- main.ts orchestration
- sync helpers
- auth/token exchange
- Drive metadata mapping for vault identity
- The most important data flow is local file state ⇄ sync engine ⇄ Drive objects, with auth mediated by the external token service.
Main entry points: main.ts Main · drive.ts Drive API · push.ts Push · pull.ts Pull
Components 17
Obsidian runtime
Plugin code running inside the Obsidian app against the local vault
- Main · Registers commands and orchestrates sync flows inside Obsidian
main.ts - Pull · Reconciles local state from Google Drive into the vault
helpers/pull.ts - Push · Pulls first, then uploads local changes to Drive
helpers/push.ts - Reset · Re-baselines the local vault to match Drive state
helpers/reset.ts - Drive API · Centralized Google Drive operations and vault/file mapping
helpers/drive.ts - HTTP client · Shared HTTP transport for Drive and token-service calls
helpers/ky.ts - Vault · Obsidian-managed local note store and change boundary
- Commands · Ribbon button and command-palette entry points into sync
- Reconcile · Local-first reconciliation with automatic conflict resolution
Remote services
Google Drive storage and the external token broker used for auth
- Token broker · Converts refresh tokens to access tokens and provides a connectivity ping
- Google Drive · Canonical remote store for synced vault content
- Vault mapping · Associates a vault with its Drive folder and metadata
Build and release
Bundling, versioning, and publishing metadata for the plugin
- Bundler · Produces the distributable plugin bundle
esbuild.config.mjs - Manifest · Obsidian plugin package metadata and compatibility info
manifest.json - Versions · Version-to-release compatibility metadata
versions.json - Version bump · Automates plugin version updates during release
version-bump.mjs - Release CI · GitHub Actions pipeline for building and releasing the plugin
.github/workflows/release.yml
Connections 27
- Commands → Main: invoke · User commands and ribbon actions enter the plugin through the main orchestrator
- Main → Pull: dispatch · Main routes the pull command into the pull workflow
- Main → Push: dispatch · Main routes the push command into the push workflow
- Main → Reset: dispatch · Main routes the reset command into the resync workflow
- Main → Drive API: coordinate · Main shares the Drive adapter across sync modes
- Main → HTTP client: coordinate · Main relies on shared HTTP plumbing for remote requests
- Main → Vault: read/write · The plugin operates on the Obsidian-managed local vault
- Pull → Drive API: fetch · Pull reads remote Drive state through the adapter
- Pull → Vault: apply · Pulled remote changes are written into the vault
- Push → Pull: pre-sync · Push performs a pull first before uploading local changes
- Push → Drive API: upload · Push sends local file changes through the Drive adapter
- Push → Vault: scan · Push inspects local vault state before uploading
- Reset → Drive API: baseline · Reset rebuilds local state from remote Drive contents
- Reset → Vault: overwrite · Reset aligns the vault to the chosen remote baseline
- Drive API → Google Drive: api calls · The Drive adapter is the repository's remote storage boundary
- Drive API → Vault mapping: map identity · Drive metadata binds files to the correct vault and folder
- Vault mapping → Google Drive: folder metadata · Vault identity is represented in Drive folder structure and properties
- HTTP client → Token broker: token exchange · HTTP client requests access tokens from the external broker
- HTTP client → Google Drive: http transport · Shared client also carries Drive API requests
- Reconcile → Pull: policy · Reconciliation rules shape how pull resolves differences
- Reconcile → Push: policy · Reconciliation rules shape upload order and precedence
- Reconcile → Reset: policy · Reset uses the same state-alignment rules in destructive form
- Release CI → Version bump: run · CI drives automated version updates during release
- Release CI → Bundler: build · Release workflow bundles the plugin for distribution
- Version bump → Manifest: update · Release automation keeps plugin metadata in sync
- Version bump → Versions: update · Release automation updates compatibility mappings
- Bundler → Manifest: package · Bundling targets the Obsidian plugin package structure