Feature: Local-first backup, restore, and sync workflow

[hoangsonww]

Summary

Add a local-first sync, backup, and restore workflow so users can move dashboard state between machines, recover from database loss, and optionally keep multiple installs up to date without running a central hosted service.

Problem / Opportunity

The project already supports JSON export, cleanup, import of Claude history, and operational backup guidance. Those are useful primitives, but they do not provide an end-to-end product workflow for preserving dashboard state, restoring it onto a fresh install, or reconciling data collected on multiple developer machines.

Claude Code users often work across laptops, desktops, containers, and remote dev boxes. A monitoring platform is more valuable when sessions, cost history, pricing rules, dashboard runs, and user settings can be backed up and restored predictably while preserving the repository's local-first posture.

Proposed Feature

Create a guided backup/restore and optional sync workflow built around signed manifest files and idempotent merge semantics. The feature should produce portable bundles, validate them before import, show a dry-run diff, and merge records without duplicating sessions, agents, events, token usage, pricing rules, or dashboard run history.

Scope

• Add a backup bundle format containing a manifest, schema version, export metadata, database records, and optional compressed payload chunks for large event sets.
• Add restore endpoints that validate a bundle, report compatibility, show a dry-run summary, and then apply an idempotent merge.
• Support conflict handling for mutable records such as model pricing and settings with clear choices: keep local, use incoming, or duplicate as a named profile where appropriate.
• Add a Settings UI flow for creating backups, validating uploads, previewing restore impact, and tracking restore progress over WebSocket.
• Add optional local sync targets such as a user-selected folder, network-mounted directory, or Git-ignored backup folder, with manual and scheduled runs.
• Include MCP/CLI affordances so agents can trigger backup status checks and create backups under explicit configuration gates.
• Document the bundle format, compatibility policy, and recovery procedure.

Acceptance Criteria

• Users can create a portable backup bundle from Settings that includes sessions, agents, events, token usage, model pricing, dashboard runs, and relevant non-secret dashboard settings.
• Users can upload or select a backup bundle and see a dry-run summary before any database mutation occurs.
• Restore is idempotent: reapplying the same bundle does not duplicate sessions, events, agents, token rows, or dashboard runs.
• Restore preserves active local data unless the user explicitly chooses a conflict strategy for mutable settings/pricing records.
• Large backups stream progress over WebSocket and do not block the server event loop for long-running imports.
• Backup and restore operations are covered by server tests for schema versioning, corrupt manifests, partial bundles, duplicate records, and conflict handling.
• Documentation explains how this differs from raw JSON export and how to recover a fresh install from a bundle.

Non-Goals

• Building a hosted cloud sync service.
• Real-time multi-writer replication.
• Syncing raw Claude Code transcript files outside the dashboard's own persisted records.
• Storing secrets or unredacted Claude configuration in backup bundles.

Dependencies / Risks

• Merge semantics need to respect existing SQLite constraints and future schema migrations.
• Large event tables may require chunked export/import and progress reporting to avoid memory spikes.
• Sync targets must stay explicit and local-first to avoid surprising data exfiltration.

Open Questions

• Should scheduled backups be disabled by default and gated behind an explicit local path selection?
• Should backup bundles be optionally encrypted with a user-provided passphrase?
• Should restore support selective scopes, such as only pricing/settings or only sessions within a date range?

[LeoLin990405]

Starting on this. Given the breadth here, I'd like to land it in focused PRs rather than one mega-change — PR 1 = the backup bundle + validated, idempotent restore core (the highest-value part: recover a fresh install from a bundle), with sync targets / scheduling / MCP-CLI affordances as follow-up PRs. Flagging scope so you can steer before I build.

PR 1 scope

• Backup bundle (GET /api/backup/export) — a portable JSON bundle with a manifest (format, schema_version, app version, ISO created_at, per-table counts) + data for the DB tables: sessions, agents, events, token_usage, model_pricing, dashboard_runs. This is distinct from the existing /api/settings/export raw dump (which has no manifest/versioning and no restore path) — I'll document the difference.
• Validate (POST /api/backup/validate) — checks the manifest + schema_version compatibility + structure, returns a compatibility report (no mutation).
• Dry-run (POST /api/backup/dry-run) — per-table summary of what would change (new vs already-present, + pricing conflicts) with zero DB mutation, so the user previews before applying.
• Idempotent restore (POST /api/backup/restore) — merge in a single transaction. Append-only tables (sessions/agents/events/token_usage/dashboard_runs) are INSERT OR IGNORE by primary key, so reapplying the same bundle never duplicates and active local data is preserved. model_pricing (the one mutable, config-like table) honors a conflict strategy: keep_local (default) or use_incoming.
• Upload is a multipart file (matches the existing import path) so large bundles aren't capped by the JSON body limit.
• Settings UI: a Backup & Restore section — Download backup + Restore-from-file with the dry-run preview and conflict-strategy choice before apply.
• Docs + server tests (schema versioning, corrupt/partial manifest, duplicate records → idempotency, pricing conflict handling).

Deferred to follow-up PRs (called out so this one stays reviewable): WebSocket streaming progress + compressed chunking for very large bundles (PR 1 restores transactionally, fast for typical sizes), local sync targets (folder/network) + scheduled sync, and MCP/CLI affordances. Non-secret settings aren't a DB table here (they're env/file config), so the bundle covers DB recovery; happy to add a settings-capture step if you want it.

Sound right? Will reference this issue in the PR.