# codedrichy/obsidianbridge architecture

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

- Interactive diagram: https://gitdiagram.com/codedrichy/obsidianbridge
- Repository: https://github.com/codedrichy/obsidianbridge

## Overview

1. **What this repository is**
   - A single-user Python desktop app that runs in the background as a tray utility.
   - Its job is to keep an Obsidian vault in sync with selected GitHub project folders, but only in one direction: source folders → vault.

2. **Primary runtime boundary**
   - The application lives mainly in `ObsidianBridge.py`, which is the central runtime entrypoint.
   - The rest of the repo is support for launching, packaging, shortcut creation, and documentation.
   - This is not a client/server system; the core deployment model is a local desktop process.

3. **Source-side subsystem**
   - The app watches a configured source directory, typically a GitHub workspace.
   - It reacts to file system changes in real time, with debounce and collision-delay behavior to avoid syncing half-written files or rapid duplicate events.
   - The source boundary intentionally excludes git metadata and large/unwanted files.

4. **Sync processing pipeline**
   - When a file changes, the app does a guarded sync sequence: detect change, wait, check for conflicts, back up the destination file, transform content, write to the vault, then clean up.
   - This pipeline is designed to preserve stability rather than mirror the source byte-for-byte.

5. **Content transformation layer**
   - Markdown is not copied blindly.
   - Wiki-links are rewritten so they remain valid inside Obsidian.
   - Structure preservation is configurable, which affects how source folder paths map into the vault.

6. **Destination-side subsystem**
   - The destination is an Obsidian vault that stores processed copies, not live links back to GitHub.
   - This boundary is important: Obsidian reads a clean, fast local knowledge store, while GitHub remains the source of truth.

7. **Navigation/index generation**
   - The app generates index files to make folders appear as connected nodes in Obsidian’s graph and to create hierarchical navigation.
   - The architecture is explicitly folder-aware: project root index → subfolder indexes → content files.
   - These generated files are part of the vault output, not source material.

8. **Optional AI tagging integration**
   - There is an optional dependency on an Ollama model server for automatic tagging.
   - When enabled, this acts as an enrichment step inside the sync pipeline, not as a separate service.
   - If disabled or unavailable, the core sync still functions.

9. **Safety and resilience**
   - Backups are created before writes, with retention of recent backups and rollback on failure.
   - There is a file-size cutoff to avoid syncing very large files.
   - These safeguards are central to the architecture because the app is continuously mutating a second copy of source content.

10. **User control plane**
   - The app exposes a system tray UI and a status window for monitoring sync activity.
   - Main controls include force sync, pause/resume watching, open vault, and open settings.
   - This indicates a background daemon with manual override controls rather than a purely hands-off service.

11. **Configuration and operational state**
   - Runtime behavior is driven by settings such as source path, destination path, structure preservation, tagging, and debounce/collision timing.
   - Logs and config are local files, so the app is self-contained and desktop-oriented.

12. **Distribution and packaging**
   - `Launch ObsidianBridge.bat` and related batch files provide quick start on Windows.
   - `build_exe.py` suggests packaging into a standalone executable for distribution.
   - `create_shortcuts.py` supports desktop/start-menu installation convenience.

13. **How to draw the architecture**
   - Model it as: local source workspace on the left, ObsidianBridge processing core in the center, Obsidian vault on the right.
   - Add an optional side integration to Ollama.
   - Show a one-way, event-driven sync flow with preprocessing, safety checks, and generated indexes between source and vault.

Main entry points: [`ObsidianBridge.py`](https://github.com/codedrichy/obsidianbridge/blob/main/ObsidianBridge.py) (Sync engine), [`Launch ObsidianBridge.bat`](https://github.com/codedrichy/obsidianbridge/blob/HEAD/Launch%20ObsidianBridge.bat) (Launchers), [`build_exe.py`](https://github.com/codedrichy/obsidianbridge/blob/main/build_exe.py) (Packager), [`create_shortcuts.py`](https://github.com/codedrichy/obsidianbridge/blob/main/create_shortcuts.py) (Shortcut maker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_source["Source workspace"]
  node_source_workspace[("Source folders<br/>workspace")]
end

subgraph group_core["ObsidianBridge core"]
  node_watcher(("Watcher<br/>fs monitor<br/>[ObsidianBridge.py]"))
  node_event_gate{{"Event gate<br/>debounce/conflict guard<br/>[ObsidianBridge.py]"}}
  node_sync_engine["Sync engine<br/>pipeline<br/>[ObsidianBridge.py]"]
  node_backup_mgr[("Backups<br/>safety layer<br/>[ObsidianBridge.py]")]
  node_transformer["Rewrite layer<br/>content transform<br/>[ObsidianBridge.py]"]
  node_vault_writer["Vault writer<br/>destination writer<br/>[ObsidianBridge.py]"]
  node_indexer["Index generator<br/>nav builder<br/>[ObsidianBridge.py]"]
  node_status_ui(("Tray UI<br/>control plane<br/>[ObsidianBridge.py]"))
  node_runtime_cfg["Settings<br/>config/state<br/>[ObsidianBridge.py]"]
end

subgraph group_vault["Obsidian vault"]
  node_vault_store[("Vault")]
end

subgraph group_integrations["Integrations"]
  node_tagger(("Auto tagger<br/>optional enrichment"))
  node_ollama[("Ollama<br/>model server")]
end

subgraph group_support["Support tooling"]
  node_launcher_bat["Launchers<br/>startup scripts"]
  node_packager["Packager<br/>build tool<br/>[build_exe.py]"]
  node_shortcuts["Shortcut maker<br/>installer helper"]
end

node_source_workspace -->|"changes"| node_watcher
node_watcher -->|"debounce"| node_event_gate
node_event_gate -->|"sync"| node_sync_engine
node_sync_engine -->|"backup"| node_backup_mgr
node_sync_engine -->|"transform"| node_transformer
node_transformer -->|"enrich"| node_tagger
node_tagger -.->|"model call"| node_ollama
node_sync_engine -->|"write"| node_vault_writer
node_vault_writer -->|"store"| node_vault_store
node_sync_engine -->|"generate indexes"| node_indexer
node_indexer -->|"publish"| node_vault_store
node_backup_mgr -.->|"rollback"| node_vault_writer
node_status_ui -->|"control"| node_sync_engine
node_status_ui -->|"settings"| node_runtime_cfg
node_launcher_bat -.->|"start"| node_status_ui
node_packager -.->|"bundle"| node_launcher_bat
node_shortcuts -.->|"install"| node_launcher_bat
node_runtime_cfg -->|"configure"| node_watcher
node_runtime_cfg -->|"configure"| node_sync_engine
node_runtime_cfg -->|"toggle"| node_tagger

click node_watcher "https://github.com/codedrichy/obsidianbridge/blob/main/ObsidianBridge.py"
click node_event_gate "https://github.com/codedrichy/obsidianbridge/blob/main/ObsidianBridge.py"
click node_sync_engine "https://github.com/codedrichy/obsidianbridge/blob/main/ObsidianBridge.py"
click node_backup_mgr "https://github.com/codedrichy/obsidianbridge/blob/main/ObsidianBridge.py"
click node_transformer "https://github.com/codedrichy/obsidianbridge/blob/main/ObsidianBridge.py"
click node_vault_writer "https://github.com/codedrichy/obsidianbridge/blob/main/ObsidianBridge.py"
click node_indexer "https://github.com/codedrichy/obsidianbridge/blob/main/ObsidianBridge.py"
click node_status_ui "https://github.com/codedrichy/obsidianbridge/blob/main/ObsidianBridge.py"
click node_runtime_cfg "https://github.com/codedrichy/obsidianbridge/blob/main/ObsidianBridge.py"
click node_launcher_bat "https://github.com/codedrichy/obsidianbridge/blob/main/Launch ObsidianBridge.bat"
click node_packager "https://github.com/codedrichy/obsidianbridge/blob/main/build_exe.py"
click node_shortcuts "https://github.com/codedrichy/obsidianbridge/blob/main/create_shortcuts.py"

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_source_workspace toneBlue
class node_watcher,node_event_gate,node_sync_engine,node_backup_mgr,node_transformer,node_vault_writer,node_indexer,node_status_ui,node_runtime_cfg toneAmber
class node_vault_store toneMint
class node_tagger,node_ollama toneRose
class node_launcher_bat,node_packager,node_shortcuts toneIndigo
```

## Components

### Source workspace

GitHub project folders monitored for changes

- **Source folders**: workspace · Selected local GitHub project directories and files

### ObsidianBridge core

Local desktop process that watches, filters, transforms, and syncs content

- [Watcher](https://github.com/codedrichy/obsidianbridge/blob/main/ObsidianBridge.py): fs monitor · Background file system monitor for source changes · `ObsidianBridge.py`
- [Event gate](https://github.com/codedrichy/obsidianbridge/blob/main/ObsidianBridge.py): debounce/conflict guard · Debounce and collision-delay logic before sync · `ObsidianBridge.py`
- [Sync engine](https://github.com/codedrichy/obsidianbridge/blob/main/ObsidianBridge.py): pipeline · Coordinates guarded one-way source to vault sync · `ObsidianBridge.py`
- [Backups](https://github.com/codedrichy/obsidianbridge/blob/main/ObsidianBridge.py): safety layer · Pre-write backup, retention, and rollback handling · `ObsidianBridge.py`
- [Rewrite layer](https://github.com/codedrichy/obsidianbridge/blob/main/ObsidianBridge.py): content transform · Markdown processing and wiki-link rewriting · `ObsidianBridge.py`
- [Vault writer](https://github.com/codedrichy/obsidianbridge/blob/main/ObsidianBridge.py): destination writer · Writes processed files into the Obsidian vault · `ObsidianBridge.py`
- [Index generator](https://github.com/codedrichy/obsidianbridge/blob/main/ObsidianBridge.py): nav builder · Creates folder index files for vault navigation and graph connectivity · `ObsidianBridge.py`
- [Tray UI](https://github.com/codedrichy/obsidianbridge/blob/main/ObsidianBridge.py): control plane · System tray and status window controls · `ObsidianBridge.py`
- [Settings](https://github.com/codedrichy/obsidianbridge/blob/main/ObsidianBridge.py): config/state · Source path, destination path, timing, structure, and tagging settings · `ObsidianBridge.py`

### Obsidian vault

Processed destination vault with generated navigation files

- **Vault**: obsidian vault · Local destination knowledge store

### Integrations

Optional external enrichment services

- **Auto tagger**: optional enrichment · Optional Ollama-based tagging step inside sync
- **Ollama**: model server · Optional local model server used for tagging

### Support tooling

Launch, packaging, and shortcut helpers

- [Launchers](https://github.com/codedrichy/obsidianbridge/blob/HEAD/Launch%20ObsidianBridge.bat): startup scripts · Windows batch launch entry points · `Launch ObsidianBridge.bat`
- [Packager](https://github.com/codedrichy/obsidianbridge/blob/main/build_exe.py): build tool · Standalone executable build script · `build_exe.py`
- [Shortcut maker](https://github.com/codedrichy/obsidianbridge/blob/main/create_shortcuts.py): installer helper · Desktop and start-menu shortcut creation · `create_shortcuts.py`

## Connections

- Source folders → Watcher: changes · File system activity enters the monitor
- Watcher → Event gate: debounce · Filters rapid events and collision windows
- Event gate → Sync engine: sync · Approved changes enter the guarded sync flow
- Sync engine → Backups: backup · Creates destination backup before writing
- Sync engine → Rewrite layer: transform · Prepares content for Obsidian-friendly storage
- Rewrite layer → Auto tagger: enrich · Optional tagging step when enabled
- Auto tagger → Ollama: model call · Uses local Ollama server when available
- Sync engine → Vault writer: write · Sends processed content to the destination writer
- Vault writer → Vault: store · Persists processed files into the vault
- Sync engine → Index generator: generate indexes · Builds folder and graph-navigation index files
- Index generator → Vault: publish · Writes generated index files into the vault
- Backups → Vault writer: rollback · Restores prior content on failure
- Tray UI → Sync engine: control · Force sync, pause/resume, and manual override actions
- Tray UI → Settings: settings · Displays and edits operational configuration
- Launchers → Tray UI: start · Launches the desktop background app
- Packager → Launchers: bundle · Supports distribution packaging and launch artifacts
- Shortcut maker → Launchers: install · Creates convenient desktop/start-menu entry points
- Settings → Watcher: configure · Controls source path and watch behavior
- Settings → Sync engine: configure · Controls debounce, collision, structure, and file limits
- Settings → Auto tagger: toggle · Enables or disables AI tagging
