TrueGrowth/openspec/changes/unify-local-data-persistence/design.md

Context

The desktop shell already pins Electron userData, but development Local API runs can still default to .truegrowth-runtime, while packaged or Electron-launched runs use Application Support/TrueGrowth/runtime. Browser localStorage and IndexedDB are origin scoped, so 127.0.0.1:7200 and preview ports cannot share data directly.

Goals / Non-Goals

• Goals: make desktop business data survive restarts and port changes, expose storage health, migrate legacy runtime records, and avoid duplicating large media files.
• Non-Goals: rewrite every browser IndexedDB cache in one step, delete legacy runtime folders, or bundle a new native database dependency.

Decisions

• Use ~/Library/Application Support/TrueGrowth/data/truegrowth.sqlite (platform equivalent on Windows/Linux) as the canonical ledger.
• Continue using the existing sqlite3 CLI integration pattern to avoid adding native npm dependencies.
• Store structured business records as JSON payloads in typed ledger tables, with a kv table for aggregate state and migration markers.
• Keep JSON shadows during migration for compatibility, but prefer SQLite reads whenever available.
• Index legacy large files by absolute path and local media URL; do not copy the 35GB .truegrowth-runtime tree by default.

Risks / Trade-offs

• SQLite CLI may be missing on a fresh machine. Mitigation: diagnostics report unavailable status and Local API falls back to existing JSON behavior until the runtime readiness flow installs or bundles SQLite.
• Browser-only IndexedDB data cannot be read by Node without Chromium internals. Mitigation: make the desktop Local API the authoritative source going forward and keep browser storage as a transitional source.
• Migration may discover stale or deleted files. Mitigation: diagnostics report missing targets and preserve legacy source metadata.

Migration Plan

1. Create canonical data/runtime directories under desktop user data.
2. Initialize ledger schema and record current storage roots.
3. Import legacy runtime tasks, cleared task IDs, business workflow JSON/SQLite state, AIGCPanel state, social publishing state, and media file indexes.
4. Keep legacy files untouched and record migration versions in storage_migrations.
5. Expose diagnostics so support can see which roots are active and which legacy sources were imported.