# silvanocerza/github-gitless-sync architecture

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

- Interactive diagram: https://gitdiagram.com/silvanocerza/github-gitless-sync
- Repository: https://github.com/silvanocerza/github-gitless-sync

## Overview

##### Project type and purpose
- This is an Obsidian community plugin (“GitHub Gitless Sync”) that synchronizes a local Obsidian vault with a GitHub repository purely via REST calls—no `git` executable.
- Its core use case: bidirectional sync (push/pull) between multiple vaults and GitHub, with automatic/manual triggers and built-in conflict resolution UI.

##### File structure
- Top-level:
- manifest.json / manifest-beta.json → plugin metadata for Obsidian
- esbuild.config.mjs, version-bump.mjs → build & release pipeline
- assets → screenshots used in README/settings
- src → all TypeScript source code
- src subfolders:
- github → HTTP client for GitHub REST API
- settings → configuration UI & storage
- views → React/TSX components for conflict-resolution views (split/unified)
- utilities: logger.ts, utils.ts
- core orchestration: main.ts, events-listener.ts, sync-manager.ts, metadata-store.ts
- Configuration & metadata: package.json, tsconfig.json, versions.json.

##### README insights
- Describes plugin features, UI screens, token requirements, first-sync constraints, conflict-resolution modes, config-folder sync, and reset workflow.
- Emphasizes mobile/desktop support via same logic, and reliance on GitHub REST APIs over `git`.

a. Main components to include:
- Obsidian Host (Electron or Mobile runtime)
- Plugin Entry & Event Listener (main.ts + events-listener.ts)
- Settings Module (src/settings)
- Sync Manager (src/sync-manager.ts)
- Metadata Store (src/metadata-store.ts)
- GitHub Client (src/github/client.ts)
- Local Vault File System (Obsidian vault folder)
- Conflict Resolution UI (src/views/conflicts-resolution)
- Logger & Utilities
- Build Pipeline (esbuild, version bump scripts)
- External Service: GitHub REST API

b. Relationships & interactions:
1. User triggers sync via UI ribbon/button → Event Listener
2. Event Listener invokes Sync Manager
3. Sync Manager consults Metadata Store to determine changed files
4. For remote operations, Sync Manager calls GitHub Client → GitHub REST API
5. For local operations, Sync Manager reads/writes vault files via Obsidian file API
6. If conflicts arise, Sync Manager launches Conflict Resolution UI (split/unified)
7. User resolves conflicts in UI → Sync Manager finalizes resolution and updates Metadata Store
8. Settings Module supplies config (token, repo, branch) to Sync Manager
9. Logger captures events at each stage

c. Architectural patterns/design principles:
- Modular separation: core orchestration vs. UI vs. HTTP client vs. storage
- Event-driven: Obsidian plugin lifecycle & command registration
- MVC-style within plugin:
- Model = Metadata Store + Settings
- View = Conflict Resolution React components
- Controller = Sync Manager + Event Listener
- Single-responsibility: each TS file handles a discrete function
- Build-time bundling via esbuild ensures a lightweight plugin deliverable

d. Key technologies/frameworks:
- Obsidian Plugin API (TypeScript)
- React/TSX for in-vault UI
- esbuild for bundling
- GitHub REST API (via custom client)
- PNPM / npm for dependency management

##### Be detailed but concise
- Every logical piece: plugin entry, settings, sync logic, storage, UI, external API
- Avoid over-splitting: group helpers (logger, utils) under “Utilities” unless they’re central

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    ObsidianHost["Obsidian Host (Electron/Mobile)"]:::external
    GitHubAPI["GitHub REST API"]:::external

    %% Plugin Metadata & Build
    PluginMetadata["Plugin Metadata\n(manifest.json, manifest-beta.json)"]:::util
    BuildPipeline["Build Pipeline\n(esbuild.config.mjs,\nversion-bump.mjs)"]:::build

    %% Plugin Bundle
    subgraph "Plugin Bundle"
        direction TB
        subgraph "Entry & Listener" 
            direction TB
            Entry["Plugin Entry\n(src/main.ts)"]:::core
            EventListener["Event Listener\n(src/events-listener.ts)"]:::core
        end

        subgraph "Core Modules"
            direction TB
            SyncManager["Sync Manager\n(src/sync-manager.ts)"]:::core
            MetadataStore["Metadata Store\n(src/metadata-store.ts)"]:::core
            GitHubClient["GitHub Client\n(src/github/client.ts)"]:::core
            Utilities["Utilities\n(src/logger.ts,\nsrc/utils.ts)"]:::util
        end

        subgraph "UI Components"
            direction TB
            subgraph "Settings Module" 
                SettingsMain["Settings\n(src/settings/settings.ts)"]:::ui
                SettingsTab["Settings Tab\n(src/settings/tab.ts)"]:::ui
            end

            subgraph "Conflict Resolution UI"
                direction TB
                subgraph "Unified View"
                    UnifiedViewDir["Unified View\n(src/views/conflicts-resolution/unified-view)"]:::ui
                end
                subgraph "Split View"
                    SplitViewDir["Split View\n(src/views/conflicts-resolution/split-view)"]:::ui
                end
                CommonView["Common Conflict View\n(src/views/conflicts-resolution/diff.ts,\nview.tsx)"]:::ui
                Hooks["Hooks\n(src/views/hooks.ts)"]:::ui
            end
        end
    end

    %% Local Vault
    VaultFS["Local Vault File System\n(Obsidian API)"]:::external

    %% Connections
    ObsidianHost -->|"command/button click"| Entry
    Entry --> EventListener
    EventListener -->|"invoke sync"| SyncManager
    SettingsMain -->|"provide config"| SyncManager
    SettingsTab --> SyncManager
    SyncManager --> MetadataStore
    SyncManager --> VaultFS
    SyncManager --> GitHubClient
    GitHubClient -->|"REST calls"| GitHubAPI
    SyncManager -->|"if conflicts"| UnifiedViewDir
    SyncManager --> SplitViewDir
    SyncManager --> CommonView
    UnifiedViewDir -->|resolution result| SyncManager
    SplitViewDir -->|resolution result| SyncManager
    CommonView -->|hooks| Hooks
    SyncManager --> Utilities
    MetadataStore --> Utilities
    GitHubClient --> Utilities

    %% External integrations
    PluginMetadata --> Entry
    BuildPipeline --> Entry

    %% Click Events
    click Entry "https://github.com/silvanocerza/github-gitless-sync/blob/main/src/main.ts"
    click EventListener "https://github.com/silvanocerza/github-gitless-sync/blob/main/src/events-listener.ts"
    click SettingsMain "https://github.com/silvanocerza/github-gitless-sync/blob/main/src/settings/settings.ts"
    click SettingsTab "https://github.com/silvanocerza/github-gitless-sync/blob/main/src/settings/tab.ts"
    click SyncManager "https://github.com/silvanocerza/github-gitless-sync/blob/main/src/sync-manager.ts"
    click MetadataStore "https://github.com/silvanocerza/github-gitless-sync/blob/main/src/metadata-store.ts"
    click GitHubClient "https://github.com/silvanocerza/github-gitless-sync/blob/main/src/github/client.ts"
    click UnifiedViewDir "https://github.com/silvanocerza/github-gitless-sync/tree/main/src/views/conflicts-resolution/unified-view"
    click SplitViewDir "https://github.com/silvanocerza/github-gitless-sync/tree/main/src/views/conflicts-resolution/split-view"
    click CommonView "https://github.com/silvanocerza/github-gitless-sync/blob/main/src/views/conflicts-resolution/diff.ts"
    click Hooks "https://github.com/silvanocerza/github-gitless-sync/blob/main/src/views/hooks.ts"
    click Utilities "https://github.com/silvanocerza/github-gitless-sync/blob/main/src/logger.ts"
    click Utilities "https://github.com/silvanocerza/github-gitless-sync/blob/main/src/utils.ts"
    click BuildPipeline "https://github.com/silvanocerza/github-gitless-sync/blob/main/esbuild.config.mjs"
    click BuildPipeline "https://github.com/silvanocerza/github-gitless-sync/blob/main/version-bump.mjs"
    click PluginMetadata "https://github.com/silvanocerza/github-gitless-sync/blob/main/manifest.json"
    click PluginMetadata "https://github.com/silvanocerza/github-gitless-sync/blob/main/manifest-beta.json"
    click VaultFS "https://github.com/silvanocerza/github-gitless-sync/blob/main/mock-obsidian.ts"

    %% Styles
    classDef core fill:#E0F3FF,stroke:#0091EA,stroke-width:2px
    classDef ui fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px
    classDef external fill:#FFF3E0,stroke:#EF6C00,stroke-width:2px
    classDef build fill:#ECEFF1,stroke:#607D8B,stroke-width:2px
    classDef util fill:#F5F5F5,stroke:#9E9E9E,stroke-width:2px
```
