# ufebri/ray-vault-sync architecture

> Architecture diagram of the GitHub repository ufebri/ray-vault-sync, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ufebri/ray-vault-sync
- Repository: https://github.com/ufebri/ray-vault-sync

## Overview

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: [`src/sync-core.ts`](https://github.com/ufebri/ray-vault-sync/blob/main/src/sync-core.ts) (Sync Engine), [`src/main.ts`](https://github.com/ufebri/ray-vault-sync/blob/main/src/main.ts) (Plugin Controller), [`src/local-vault.ts`](https://github.com/ufebri/ray-vault-sync/blob/main/src/local-vault.ts) (Local Vault Adapter), [`src/diagnostics.ts`](https://github.com/ufebri/ray-vault-sync/blob/main/src/diagnostics.ts) (Diagnostics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_plugin["Obsidian Plugin"]
  node_plugin["Plugin Controller<br/>[main.ts]"]
  node_mobile["Mobile Sync Widget<br/>[mobile-widget.ts]"]
end

subgraph group_reconcile["Sync and Reconciliation"]
  node_engine["Sync Engine<br/>[sync-core.ts]"]
  node_plan["Change Plan<br/>[sync-core.ts]"]
  node_conflicts["Conflict Preservation<br/>[sync-core.ts]"]
  node_commit["Commit Assembly<br/>[sync-core.ts]"]
end

subgraph group_integration["Vault and GitHub"]
  node_local["Local Vault Adapter<br/>[local-vault.ts]"]
  node_syncstate["Sync State File<br/>[local-vault.ts]"]
  node_github["GitHub Client<br/>[github-client.ts]"]
end

subgraph group_support["Configuration and Health"]
  node_settings["Settings UI<br/>[settings.ts]"]
  node_diagnostics["Diagnostics<br/>[diagnostics.ts]"]
  node_settingsdata["Plugin Settings Data<br/>[main.ts]"]
  node_report["Diagnostics Report<br/>[diagnostics.ts]"]
end

node_user(("Vault User"))
node_obsidian[("Obsidian Vault")]
node_api["GitHub REST API"]
node_repository[("GitHub Repository")]

node_user -->|"starts sync"| node_plugin
node_user -->|"configures"| node_settings
node_plugin -->|"executes sync"| node_engine
node_plugin -->|"opens settings"| node_settings
node_plugin -->|"updates widget"| node_mobile
node_mobile -->|"requests sync"| node_plugin
node_settings -->|"configures auto-sync"| node_plugin
node_plugin -->|"loads and saves"| node_settingsdata
node_plugin -->|"runs diagnostics"| node_diagnostics
node_engine -->|"enumerates and reads"| node_local
node_engine -->|"fetches remote state"| node_github
node_engine -->|"calculates changes"| node_plan
node_plan -->|"identifies conflicts"| node_conflicts
node_engine -->|"preserves both versions"| node_conflicts
node_engine -->|"assembles changes"| node_commit
node_engine -->|"writes and deletes"| node_local
node_engine -->|"uploads and advances ref"| node_github
node_engine -->|"saves sync state"| node_local
node_local -->|"reads and writes files"| node_obsidian
node_local -->|"reads and writes state"| node_syncstate
node_github -->|"sends API requests"| node_api
node_api -->|"reads and commits"| node_repository
node_diagnostics -->|"checks vault"| node_local
node_diagnostics -->|"checks connectivity"| node_github
node_diagnostics -->|"previews plan"| node_engine
node_diagnostics -->|"writes report"| node_local
node_diagnostics -->|"creates"| node_report

click node_plugin "https://github.com/ufebri/ray-vault-sync/blob/main/src/main.ts"
click node_mobile "https://github.com/ufebri/ray-vault-sync/blob/main/src/mobile-widget.ts"
click node_settings "https://github.com/ufebri/ray-vault-sync/blob/main/src/settings.ts"
click node_diagnostics "https://github.com/ufebri/ray-vault-sync/blob/main/src/diagnostics.ts"
click node_engine "https://github.com/ufebri/ray-vault-sync/blob/main/src/sync-core.ts"
click node_plan "https://github.com/ufebri/ray-vault-sync/blob/main/src/sync-core.ts"
click node_conflicts "https://github.com/ufebri/ray-vault-sync/blob/main/src/sync-core.ts"
click node_commit "https://github.com/ufebri/ray-vault-sync/blob/main/src/sync-core.ts"
click node_local "https://github.com/ufebri/ray-vault-sync/blob/main/src/local-vault.ts"
click node_syncstate "https://github.com/ufebri/ray-vault-sync/blob/main/src/local-vault.ts"
click node_github "https://github.com/ufebri/ray-vault-sync/blob/main/src/github-client.ts"
click node_settingsdata "https://github.com/ufebri/ray-vault-sync/blob/main/src/main.ts"
click node_report "https://github.com/ufebri/ray-vault-sync/blob/main/src/diagnostics.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_plugin,node_mobile,node_user toneBlue
class node_engine,node_plan,node_conflicts,node_commit,node_obsidian,node_repository toneAmber
class node_local,node_syncstate,node_github,node_api toneMint
class node_settings,node_diagnostics,node_settingsdata,node_report toneRose
```

## Components

### Obsidian Plugin

- [Plugin Controller](https://github.com/ufebri/ray-vault-sync/blob/main/src/main.ts): `src/main.ts`
- [Mobile Sync Widget](https://github.com/ufebri/ray-vault-sync/blob/main/src/mobile-widget.ts): `src/mobile-widget.ts`

### Sync and Reconciliation

- [Sync Engine](https://github.com/ufebri/ray-vault-sync/blob/main/src/sync-core.ts): `src/sync-core.ts`
- [Change Plan](https://github.com/ufebri/ray-vault-sync/blob/main/src/sync-core.ts): `src/sync-core.ts`
- [Conflict Preservation](https://github.com/ufebri/ray-vault-sync/blob/main/src/sync-core.ts): `src/sync-core.ts`
- [Commit Assembly](https://github.com/ufebri/ray-vault-sync/blob/main/src/sync-core.ts): `src/sync-core.ts`

### Vault and GitHub

- [Local Vault Adapter](https://github.com/ufebri/ray-vault-sync/blob/main/src/local-vault.ts): `src/local-vault.ts`
- [Sync State File](https://github.com/ufebri/ray-vault-sync/blob/main/src/local-vault.ts): `src/local-vault.ts`
- [GitHub Client](https://github.com/ufebri/ray-vault-sync/blob/main/src/github-client.ts): `src/github-client.ts`

### Configuration and Health

- [Settings UI](https://github.com/ufebri/ray-vault-sync/blob/main/src/settings.ts): `src/settings.ts`
- [Diagnostics](https://github.com/ufebri/ray-vault-sync/blob/main/src/diagnostics.ts): `src/diagnostics.ts`
- [Plugin Settings Data](https://github.com/ufebri/ray-vault-sync/blob/main/src/main.ts): `src/main.ts`
- [Diagnostics Report](https://github.com/ufebri/ray-vault-sync/blob/main/src/diagnostics.ts): `src/diagnostics.ts`

### Other components

- **Vault User**
- **Obsidian Vault**
- **GitHub REST API**
- **GitHub Repository**

## Connections

- 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