obsidian-foundry-sync/wiki/modules/server.md

type: module path: "src/server.ts" status: active language: typescript purpose: "Local review dashboard + JSON API over the batch engine; binds 0.0.0.0:7788." maintainer: Kaysser Kayyali last_updated: 2026-06-22 linked_issues: [] depends_on: batch, push, relay-client, content-hash, foundry-block, name-uuid-resolver used_by: cli tags: [module] created: 2026-06-22 updated: 2026-06-22

server

src/server.ts — startServer(cfg) builds the index once, serves dashboard.html at / and a JSON API under /api/*. The mode (dev | apply) is fixed at startup; the UI cannot escalate to apply unless the server was started with --apply.

Mode + mirror-aware reads

• dev: writes land under --out/<bucket>/<relPath> (a mirror). resolveRefined / resolveCc read the mirror only if it exists AND is at least as new (mtime) as the real file — otherwise the real vault (edited in Obsidian) wins. This makes dev a true preview that never masks live vault edits.
• apply: targetPath writes the real refined/cc dir; writeWithBackup copies a .bak-<stamp> first (reversible).
• dry-run never writes; it collects preview entries.

Routes

Method	Path	Handler
GET	/	dashboard.html
GET	/api/index	rebuild index, return IndexResult (rebuilt every request — hash-only, cheap)
GET	/api/status	{mode, refinedDir, ccDir, outDir}
GET	/api/file?name=	per-row detail + seed/sync/re-pull previews
GET	/api/entries	Foundry journal entries (name+uuid+type) from the snapshot, for the Link picker
POST	/api/action	runAction — seed/sync/repull/import + All variants
POST	/api/push	push one note (live)
POST	/api/push-all	push every vault-newer matched note (live), baseline each
POST	/api/link	inject the foundry: identity block (link a refined-only note by uuid)
POST	/api/refresh	rebuild name-uuid.json via relay /search
GET/POST	/api/autosync	autosync status / toggle

State

{ db, cfg, index, autosync }. index is rebuilt on every /api/index and after mutating ops (push-all, link) so recommendations reflect current files.

Depends on

• batch (indexAll, row builders), push (pushNote), relay-client, content-hash, foundry-block (readFoundryBlock, splitFrontmatter), name-uuid-resolver.

Notes / gotchas

• The index's drift detection compares against LOCAL baselines + the LevelDB snapshot — not live Foundry. Live edits are only seen via the relay push/refresh path. See index-recommend.
• pushNote has no internal idempotency; the dashboard's push-all (and autosync) baseline the note's foundry.contentHash afterward so re-runs skip unchanged notes.