# stravo1/obsidian-gdrive-sync architecture

> Architecture diagram of the GitHub repository stravo1/obsidian-gdrive-sync, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stravo1/obsidian-gdrive-sync
- Repository: https://github.com/stravo1/obsidian-gdrive-sync

## Overview

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.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Obsidian Client Environment
    subgraph "Obsidian Client Environment"
        OFS["Vault File System"]:::client
        OAPI["Obsidian API"]:::client
    end

    %% Plugin Core Module
    subgraph "Plugin Core Module"
        PT["main.ts"]:::plugin
        PA["actions.js"]:::plugin
        PM["manifest.json"]:::plugin
    end

    %% External Services
    subgraph "External Services"
        GDSI["Google Drive Sync Interface"]:::external
        AS["Authentication Service"]:::external
    end

    %% Development Environment
    subgraph "Development Environment"
        ESBUILD["esbuild.config.mjs"]:::dev
        TSCONF["tsconfig.json"]:::dev
        PKG["package.json"]:::dev
    end

    %% Connections from Obsidian to Plugin Core Module
    OFS -->|"detectChange"| PT
    OAPI -->|"triggerEvents"| PT

    %% Connections from Plugin Core Module to External Services
    PT -->|"syncRequest"| GDSI
    GDSI -->|"syncResponse"| PT
    PT -->|"tokenExchange"| AS
    AS -->|"accessToken"| PT

    %% Styling classes
    classDef client fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px;
    classDef plugin fill:#e3f2fd,stroke:#0d47a1,stroke-width:2px;
    classDef external fill:#ffebee,stroke:#b71c1c,stroke-width:2px;
    classDef dev fill:#fff3e0,stroke:#e65100,stroke-width:2px;

    %% Click events for Plugin Core Module components
    click PT "https://github.com/stravo1/obsidian-gdrive-sync/blob/master/main.ts"
    click PA "https://github.com/stravo1/obsidian-gdrive-sync/blob/master/actions.js"
    click PM "https://github.com/stravo1/obsidian-gdrive-sync/blob/master/manifest.json"

    %% Click events for Development Environment components
    click ESBUILD "https://github.com/stravo1/obsidian-gdrive-sync/blob/master/esbuild.config.mjs"
    click TSCONF "https://github.com/stravo1/obsidian-gdrive-sync/blob/master/tsconfig.json"
    click PKG "https://github.com/stravo1/obsidian-gdrive-sync/blob/master/package.json"
```
