# mateusmolina/obsidian-git-file-explorer architecture

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

- Interactive diagram: https://gitdiagram.com/mateusmolina/obsidian-git-file-explorer
- Repository: https://github.com/mateusmolina/obsidian-git-file-explorer

## Overview

##### Project type and purpose
- This is an Obsidian desktop-only plugin written in TypeScript that augments Obsidian’s file explorer with Git capabilities (status badges, commit/sync widgets, diff integration, repo initialization).
- Key clues: a `manifest.json` (Obsidian plugin), `main.ts`, `src/…` handlers & widgets, README describing UI widgets and Git operations.

##### File structure
- Top-level: build configs (`esbuild.config.mjs`, `tsconfig.json`), plugin manifest, scripts (`copy-to-test-vault.mjs`, `version-bump.mjs`), `main.ts`.
- `src/`: core plugin logic
- capabilityProvider.ts – registers plugin features with Obsidian
- commandRegister.ts – CLI commands (commit, sync, diff, init repo)
- contextMenuInstaller.ts – adds right-click diff/init options
- fileExplorerHandler.ts – injects badges and widgets into UI
- git/… – GitRepository abstraction + terminalExecutor to run Git CLI
- handlers: gitDiffHandler.ts, initNewRepoHandler.ts
- settings.ts – user-configurable options
- widgets/… – UI widgets (ChangesGitWidget, SyncGitWidget, GitWidgetFactory) and utilities (eventBus, debouncer, autoSyncManager, widgetManager)
- Styles: `styles.css` for highlighting changed files.

##### Read README for additional insights
- Describes features: Git Changes Widget, Git Sync Widget (with auto-sync), Git Diff integration, file explorer enhancements, repo management.
- Mentions user interactions (click to commit or sync, context menu for diff/init), settings, and Git CLI dependency.

a. Obsidian Host
– The container application that loads the plugin via `manifest.json`.
b. Plugin Core
– `main.ts` → initializes CapabilityProvider → wires up CommandRegister and ContextMenuInstaller → loads Settings.
c. File Explorer Integration
– FileExplorerHandler injects UI elements into Obsidian’s file explorer.
d. Widgets Layer
– WidgetFactory produces widget instances (GitWidget, ChangesGitWidget, SyncGitWidget, NavColorUpdater).
– WidgetManager registers and updates widgets.
– EventBus propagates UI events (clicks) and internal triggers (auto-sync).
e. Business Logic / Handlers
– CommandRegister triggers Git operations.
– GitDiffHandler & InitNewRepoHandler handle diff and repo init.
f. Data Access / Git Abstraction
– GitRepository exposes status, commit, pull, push.
– TerminalExecutor runs Git CLI commands.
– File system as underlying data store (vault, repos).
g. Settings
– Settings module reads/writes user preferences (commit prompts, styling, auto-sync frequency).
h. External Services
– Git CLI (shell) as an external dependency.

##### Relationships and data flows
- On startup: Obsidian → loads plugin (`main.ts`) → CapabilityProvider registers event hooks.
- FileExplorerHandler listens to “file‐explorer‐render” events → uses WidgetFactory → widgets rendered in UI.
- Widgets subscribe to EventBus → on click → fire “commit” or “sync” commands → CommandRegister invokes GitRepository→ TerminalExecutor → Git CLI.
- GitRepository returns results → EventBus broadcasts updates → WidgetManager triggers widget re‐render.
- AutoSyncManager schedules periodic syncs via EventBus and Debouncer.
- Settings influence widget behavior and styling.

##### Architectural patterns
- Event-driven: EventBus decouples UI from logic.
- Factory: WidgetFactory creates widget instances.
- Manager: WidgetManager oversees widget lifecycle.
- Abstraction: GitRepository wraps TerminalExecutor to isolate Git CLI.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Obsidian Host
    subgraph "Obsidian Host"
        Obsidian["Obsidian Host"]:::external
    end
    click Obsidian "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/manifest.json"

    %% Plugin Core
    subgraph "Plugin Core"
        Main["main.ts"]:::core
        CapProv["CapabilityProvider"]:::core
        CmdReg["CommandRegister"]:::core
        CtxMenu["ContextMenuInstaller"]:::core
        Settings["Settings"]:::core
    end
    click Main "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/main.ts"
    click CapProv "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/src/capabilityProvider.ts"
    click CmdReg "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/src/commandRegister.ts"
    click CtxMenu "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/src/contextMenuInstaller.ts"
    click Settings "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/src/settings.ts"

    Obsidian -->|"loads plugin"| Main
    Main -->|"initialize"| CapProv
    Main -->|"wire up"| CmdReg
    Main -->|"install context menus"| CtxMenu
    Main -->|"load preferences"| Settings

    %% File Explorer Integration
    subgraph "File Explorer Integration"
        FEHandler["FileExplorerHandler"]:::integration
    end
    click FEHandler "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/src/fileExplorerHandler.ts"

    CapProv -->|"on file-explorer-render"| FEHandler

    %% Widgets Layer
    subgraph "Widgets Layer"
        Factory["GitWidgetFactory"]:::widgets
        BaseWidget["Widget (base)"]:::widgets
        ChangesW["ChangesGitWidget"]:::widgets
        SyncW["SyncGitWidget"]:::widgets
        GitW["GitWidget"]:::widgets
        NavUpd["NavColorUpdater"]:::widgets
        Manager["WidgetManager"]:::widgets
        EventBus["EventBus"]:::widgets
        Debouncer["Debouncer"]:::widgets
        SmartDeb["SmartDebouncer"]:::widgets
        AutoSync["AutoSyncManager"]:::widgets
    end
    click Factory "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/src/widgets/gitWidgetFactory.ts"
    click BaseWidget "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/src/widgets/widget.ts"
    click ChangesW "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/src/widgets/changesGitWidget.ts"
    click SyncW "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/src/widgets/syncGitWidget.ts"
    click GitW "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/src/widgets/gitWidget.ts"
    click NavUpd "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/src/widgets/navColorUpdater.ts"
    click Manager "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/src/widgets/widgetManager.ts"
    click EventBus "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/src/widgets/utils/eventBus.ts"
    click Debouncer "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/src/widgets/utils/debouncer.ts"
    click SmartDeb "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/src/widgets/utils/smartDebouncer.ts"
    click AutoSync "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/src/widgets/utils/autoSyncManager.ts"

    FEHandler -->|"create widgets"| Factory
    Factory --> BaseWidget
    Factory --> ChangesW
    Factory --> SyncW
    Factory --> GitW
    Factory --> NavUpd
    BaseWidget --> Manager
    ChangesW --> Manager
    SyncW --> Manager
    GitW --> Manager
    NavUpd --> Manager
    Manager --> EventBus
    Settings --> Factory
    EventBus --> Debouncer
    EventBus --> SmartDeb
    AutoSync --> EventBus
    Settings --> AutoSync

    %% Business Logic / Handlers
    subgraph "Business Logic / Handlers"
        DiffH["GitDiffHandler"]:::logic
        InitH["InitNewRepoHandler"]:::logic
    end
    click DiffH "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/src/gitDiffHandler.ts"
    click InitH "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/src/initNewRepoHandler.ts"

    CmdReg --> DiffH
    CmdReg --> InitH
    EventBus -->|"onClick: diff"| DiffH
    EventBus -->|"onClick: initRepo"| InitH

    %% Data Access / Git Abstraction
    subgraph "Data Access / Git Abstraction"
        GitRepo["GitRepository"]:::data
        TermExec["TerminalExecutor"]:::data
    end
    click GitRepo "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/src/git/gitRepository.ts"
    click TermExec "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/src/git/utils/terminalExecutor.ts"

    DiffH --> GitRepo
    InitH --> GitRepo
    CmdReg -->|"commit/pull/push"| GitRepo
    GitRepo --> TermExec
    TermExec -->|"runs Git CLI"| GitCLI

    %% External Systems
    subgraph "External Systems"
        GitCLI["Git CLI"]:::external
        FileSys["File System (Vault)"]:::external
    end

    GitCLI -->|"output"| TermExec
    FileSys --> GitRepo

    %% Build & Tooling
    subgraph "Build & Tooling"
        ESBuild["esbuild.config.mjs"]:::tooling
        TSConfig["tsconfig.json"]:::tooling
        CopyScript["copy-to-test-vault.mjs"]:::tooling
        VersionBump["version-bump.mjs"]:::tooling
        Readme["README.md"]:::tooling
    end
    click ESBuild "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/esbuild.config.mjs"
    click TSConfig "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/tsconfig.json"
    click CopyScript "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/copy-to-test-vault.mjs"
    click VersionBump "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/version-bump.mjs"
    click Readme "https://github.com/mateusmolina/obsidian-git-file-explorer/blob/master/README.md"

    %% Styles
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px
    classDef core fill:#b3e6b3,stroke:#2d862d,stroke-width:1px
    classDef integration fill:#b3d9ff,stroke:#0b5fa5,stroke-width:1px
    classDef widgets fill:#cce0ff,stroke:#3473b3,stroke-width:1px
    classDef logic fill:#ffe0b3,stroke:#b36b00,stroke-width:1px
    classDef data fill:#ffd9b3,stroke:#b36b00,stroke-width:1px
    classDef tooling fill:#e6b3ff,stroke:#800080,stroke-width:1px
```
