How codedrichy/obsidianbridge works
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 Sync engine · Launch ObsidianBridge.bat Launchers · build_exe.py Packager · create_shortcuts.py Shortcut maker
Components 16
Source workspace
GitHub project folders monitored for changes
- Source folders · Selected local GitHub project directories and files
ObsidianBridge core
Local desktop process that watches, filters, transforms, and syncs content
- Watcher · Background file system monitor for source changes
ObsidianBridge.py - Event gate · Debounce and collision-delay logic before sync
ObsidianBridge.py - Sync engine · Coordinates guarded one-way source to vault sync
ObsidianBridge.py - Backups · Pre-write backup, retention, and rollback handling
ObsidianBridge.py - Rewrite layer · Markdown processing and wiki-link rewriting
ObsidianBridge.py - Vault writer · Writes processed files into the Obsidian vault
ObsidianBridge.py - Index generator · Creates folder index files for vault navigation and graph connectivity
ObsidianBridge.py - Tray UI · System tray and status window controls
ObsidianBridge.py - Settings · Source path, destination path, timing, structure, and tagging settings
ObsidianBridge.py
Obsidian vault
Processed destination vault with generated navigation files
- Vault · Local destination knowledge store
Integrations
Optional external enrichment services
- Auto tagger · Optional Ollama-based tagging step inside sync
- Ollama · Optional local model server used for tagging
Support tooling
Launch, packaging, and shortcut helpers
- Launchers · Windows batch launch entry points
Launch ObsidianBridge.bat - Packager · Standalone executable build script
build_exe.py - Shortcut maker · Desktop and start-menu shortcut creation
create_shortcuts.py
Connections 20
- 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