obsidian-foundry-sync/_meta/overview.md

type, title, updated

type	title	updated
meta	Wiki Overview	2026-06-22

obsidian-foundry-sync — Architecture Wiki

obsidian-foundry-sync is a host-run Node/TypeScript tool that bridges Foundry VTT Campaign Codex journal data and an Obsidian vault bidirectionally. It reads the Foundry journal LevelDB, converts between Obsidian markdown and Foundry's flags.campaign-codex JSON, and pushes/pulls live through a ThreeHats rest-api relay (Foundry keeps running — no Docker stop, no LevelDB write lock).

The three pieces

1. Relay (container, docker compose up -d relay) — ThreeHats foundryvtt-rest-api-relay. Foundry's rest-api module connects OUT to it over WebSocket. API keys come from its web signup; a headless Foundry session drives it.
2. Dashboard (host-run, ./sync.sh ui, :7788) — the sync tool. JSON API + UI for seed/sync/import/link/refresh/push, and an Auto-sync toggle.
3. Vault (host path $VAULT, edited in your own Obsidian desktop app) — the Refined subdir is the tool's --vault.

Key flows

• Push (push-flow): refined note → relay /get live entry → build minimal diff (name + dot-path flags.campaign-codex) → /update. Reversible (live-entry backup).
• Refresh (refresh-flow): relay /search (minified) → name-uuid.json. Zero downtime.
• Auto-sync (autosync-watch-loop): fs.watch the vault → guard on the note's foundry.contentHash baseline → pushNote → baselineNote. Obsidian→Foundry instant. Foundry→Obsidian is manual (Sync / Re-pull) — see 005-autosync-o-to-f-only.

Key design decisions

See decisions. Headlines: external Foundry (001-external-foundry); tool stays host-run (002-tool-host-run); relay for live ops, LevelDB only for full index (003-relay-no-journal-db-no-docker-stop); browser Obsidian + plugin were dropped — the dashboard is the UI (004-dropped-browser-obsidian).

Hard rule

UI-only: if it's not in the dashboard UI, it doesn't exist. The agent runs commands; the human only does UI steps (plus the unavoidable relay-signup + Foundry-module-connect).