How ufebri/ray-vault-sync works
Ray Vault Sync is an Obsidian plugin that keeps a vault synchronized with a GitHub repository without a local Git client. The main workflow starts from a manual or scheduled sync, where the plugin configures a local-vault adapter and GitHub client, then asks the sync engine to compare local and remote files against saved base state. The engine applies uploads, downloads, deletions, and conflict preservation, then advances remote and local sync state. Settings, a mobile sidebar control, and diagnostics are separate supporting capabilities. Sync internals are sampled only in part; omitted implementation details are not inferred.
Main entry points: sync-core.ts Sync Engine · main.ts Plugin Controller · local-vault.ts Local Vault Adapter · diagnostics.ts Diagnostics
Components 17
Obsidian Plugin
- Plugin Controller
src/main.ts - Mobile Sync Widget
src/mobile-widget.ts
Sync and Reconciliation
- Sync Engine
src/sync-core.ts - Change Plan
src/sync-core.ts - Conflict Preservation
src/sync-core.ts - Commit Assembly
src/sync-core.ts
Vault and GitHub
- Local Vault Adapter
src/local-vault.ts - Sync State File
src/local-vault.ts - GitHub Client
src/github-client.ts
Configuration and Health
- Settings UI
src/settings.ts - Diagnostics
src/diagnostics.ts - Plugin Settings Data
src/main.ts - Diagnostics Report
src/diagnostics.ts
Other components
- Vault User
- Obsidian Vault
- GitHub REST API
- GitHub Repository
Connections 27
- Vault User → Plugin Controller: starts sync
- Vault User → Settings UI: configures
- Plugin Controller → Sync Engine: executes sync
- Plugin Controller → Settings UI: opens settings
- Plugin Controller → Mobile Sync Widget: updates widget
- Mobile Sync Widget → Plugin Controller: requests sync
- Settings UI → Plugin Controller: configures auto-sync
- Plugin Controller → Plugin Settings Data: loads and saves
- Plugin Controller → Diagnostics: runs diagnostics
- Sync Engine → Local Vault Adapter: enumerates and reads
- Sync Engine → GitHub Client: fetches remote state
- Sync Engine → Change Plan: calculates changes
- Change Plan → Conflict Preservation: identifies conflicts
- Sync Engine → Conflict Preservation: preserves both versions
- Sync Engine → Commit Assembly: assembles changes
- Sync Engine → Local Vault Adapter: writes and deletes
- Sync Engine → GitHub Client: uploads and advances ref
- Sync Engine → Local Vault Adapter: saves sync state
- Local Vault Adapter → Obsidian Vault: reads and writes files
- Local Vault Adapter → Sync State File: reads and writes state
- GitHub Client → GitHub REST API: sends API requests
- GitHub REST API → GitHub Repository: reads and commits
- Diagnostics → Local Vault Adapter: checks vault
- Diagnostics → GitHub Client: checks connectivity
- Diagnostics → Sync Engine: previews plan
- Diagnostics → Local Vault Adapter: writes report
- Diagnostics → Diagnostics Report: creates