How stravo1/obsidian-gdrive-sync works
Based on your file tree and README, this project is an Obsidian plugin that provides Google Drive synchronization functionality. Its primary purpose is to keep a user’s Obsidian vault in sync with a corresponding folder on Google Drive without any complex setup (e.g., no manual Git or cloud project management). The plugin integrates with Obsidian’s API to automatically detect changes to notes and then handle uploading/downloading while also managing authentication and token exchange with Google’s services.
Main Components
• Obsidian Client Environment: Representing the host application where the plugin is installed. This includes the user’s vault (the local file system of notes) and Obsidian’s API which exposes hooks and events.
• Plugin Core Module: This is implemented in main.ts (with supporting code from actions.js). It handles initialization, detecting changes in the vault, manipulating note metadata (e.g., the "lastSync" tag), and triggering file operations.
• Google Drive Interface: Representing the communication layer between the plugin and Google Drive. Include components like authentication (refresh/access tokens), file uploads (with filename encoding the full path), and downloads.
• Authentication Service: Although it’s primarily external, the design should emphasize the server responsible for the code/token exchange (as noted in the README regarding refresh token exchange). This component interacts with both the plugin and Google Drive’s OAuth endpoints.
Relationships and Interactions
• The Plugin Core Module hooks into the Obsidian Client Environment (receives events when files change, reads note metadata, and writes back the sync status).
• When a change is detected, the Plugin Core calls the Google Drive Interface to either upload new/changed notes or download missing updates.
• The Google Drive Interface relies on the Authentication Service to ensure valid tokens are available (the plugin obtains a refresh token from the user and then uses the server-mediated process to acquire an access token for Google Drive API calls).
• Data flow can be represented as a loop where changes on Obsidian trigger sync operations with Google Drive and vice versa (especially when syncing across multiple devices).
Important Architectural Patterns/Design Principles
• Event-Driven Design: The plugin listens to file changes and user interactions within Obsidian.
• Separation of Concerns: Distinct components for UI/UX in Obsidian, core sync logic, authentication handling, and external Google Drive integration.
• Dependency Management & Build Process: Leveraging ESBuild and TypeScript configuration ensures that the plugin maintains a clear structure from development to production.
• Plugin’s internal processing:
• Initialization: reading “manifest.json” and launching main.ts.
• Sync logic: Tracking changes via tags like “lastSync”.
• External operation:
• Google Drive API for file operations.
• OAuth token refresh mechanism—drawing a path from plugin to the authentication server which then communicates with Google Drive.
• Optionally, include error or exception flows where the plugin logs errors from either the local operations or remote API calls.