desktop-offline-storage-architect
Architect-level local data design for desktop apps — embedded database choice, file layout and app-data conventions, backup and corruption recovery, large local datasets, sync with a server when one exists, and the long-session durability a desktop app is expected to provide. Use when the app owns data on the user's machine.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- desktop-offline-storage-architect
- license
- MIT
- metadata
- { "crusor-path": "desktop-architect/data-architect/desktop-offline-storage-architect", "crusor-domain": "desktop-architect", "crusor-origin": "original", "crusor-sources": "sqlite.org/wal.html; sqlite.org/lang_vacuum.html; developer.apple.com/documentation/foundation/file_system; learn.microsoft.com/windows/apps/design/app-settings", "crusor-triggers": "local database, sqlite, app data, local storage, offline data, file corruption, backup, data directory, embedded database, local cache, loses data, data loss, crash recovery", "crusor-verified-on": "2026-10-30" }
- description
- Architect-level local data design for desktop apps — embedded database choice, file layout and app-data conventions, backup and corruption recovery, large local datasets, sync with a server when one exists, and the long-session durability a desktop app is expected to provide. Use when the app owns data on the user's machine.
- compatibility
- SQLite, DuckDB, LevelDB, IndexedDB, LMDB, filesystem
03 SKILL.md 正文
Desktop Offline Storage Architect
A desktop app owns durable user data. The bar is not "it saves" — it is "it survives a power cut, a full disk, and a corrupted file".
When to use
- The app stores user documents, history, or state locally.
- Choosing between SQLite, a document store, and plain files.
- Data grows to GBs, or users report lost/corrupt data.
When NOT to use
- Server-authoritative data with only a small preference cache.
- The issue is the remote schema →
website-architect/database-*.
Decision 1 — Store choice
| Store | Use for |
|---|---|
| SQLite (WAL) | relational, queries, transactions, most apps |
| DuckDB | analytical, columnar, local reporting |
| key-value (LevelDB/LMDB) | huge KV sets, caches |
| JSON/JSONL files | settings, small portable configs |
| files on disk | documents, media, exports |
- SQLite is the default answer; it is a bounded, transactional, well-understood engine.
- Do not store a database in a network/synced folder (Dropbox/OneDrive) — file locking is unreliable there. Sync via the app instead.
Decision 2 — Layout and conventions
app data dir/ (OS-correct per platform)
db/app.db transactional state
files/ user documents (content-addressed or uuid)
cache/ disposable, deletable
logs/ rotating, bounded
backups/ last N snapshots
- Cache is always safe to delete; never store anything irreplaceable there.
- Per-user vs per-machine scope is a decision; roaming profiles change the answer.
- Paths derived from the OS API, never hardcoded.
- File names sanitised; user input never becomes a path component.
Decision 3 — Durability
- WAL mode with a sensible checkpoint interval;
synchronous=NORMALis usually the right trade,FULLfor critical writes. - Transactions wrap multi-step writes; a crash mid-sequence leaves no partial state.
- Write-then-rename for atomic file replacement.
- Handle a full disk explicitly: detect, surface, and do not corrupt existing data.
- Flush before reporting success to the UI.
Decision 4 — Corruption and backup
- Assume the file can be corrupt: run
PRAGMA integrity_checkon startup after an unclean shutdown. - Keep rotating snapshots (on version change, daily, before migrations).
- Recovery path: attempt open → integrity check → restore from latest good backup → move the corrupt file aside for support (never delete it).
- Export/import a portable format so users are never trapped.
- Log the recovery event and tell the user what happened.
Decision 5 — Scale
- Index for the queries the UI actually runs; a full scan on 2 GB is a bug.
- Paginate reads; never load a whole table into memory for a list view.
- Vacuum/compact on a schedule or after large deletes; disk grows otherwise.
- Blobs: filesystem with references in the DB, unless you need transactional blobs and the size is small.
- Measure: open time and query time on a production-size dataset.
Decision 6 — Sync with a server
- The local DB is authoritative for the session; the server is authoritative for shared state — decide per entity.
- Sync via the app's API with ids and versions; never by syncing the database file.
- Conflicts resolved per field; deletions as tombstones.
- Offline queue survives restarts and is idempotent on replay.
Failure modes at scale
- Database inside a Dropbox folder; two machines, one corrupted file.
- No backup before migration; a failed upgrade destroys history.
- Cache directory used for user documents, purged by a cleaner.
- Full disk during save; the app truncates the file and reports success.
- Startup integrity check absent; every user sees a crash loop after a power cut.
Verification receipts
- Store choice and layout documented with the OS-correct paths.
- Crash test: kill mid-write, data intact, WAL recovers.
- Corruption drill: truncate the DB file, recovery path restores from backup.
- Full-disk test: write fails cleanly, existing data untouched.
- Open and query timings on a production-size dataset.
04 同仓库更多 Skills
interaction-patterns-architect
Architect-level interaction design in code — choosing established patterns over invented ones, feedback and latency behaviour, destructive-action safeguards, navigation and overlay conventions, and the state model behind every interactive surface. Use when a screen has to behave, not just look.
design-system-ops-architect
Architect-level operation of a design system in code — token pipelines and versioning, component API and variant policy, the catalogue as the contract, adoption metrics, and the governance that stops a system from forking into three. Use when a component library must survive several teams.
design-handoff-architect
Architect-level design handoff — what must be specified before implementation starts, tokens over raw values, responsive and content-limit contracts, state matrices, and the review loop that catches drift between design and code. Use when a design is about to become code.
content-microcopy-architect
Architect-level UI content — where strings live, voice and terminology consistency, error and empty-state copy as part of the interface, translation-ready authoring, and the content model a product needs before it multiplies screens. Use when the words in the interface matter as much as the pixels.
ui-ux-implementation-architect
Architect-level direction for turning a design into working UI — the handoff contract, component ownership versus screen-level layout, interaction and state conventions, design QA gates, and the review habits that keep an implementation faithful without frozen pixels. Use before any specific UI implementation skill.
test-strategy-architect
Architect-level test strategy — allocating assertions across unit, integration, contract and end-to-end layers, designing for testability through dependency boundaries, fixture and data strategy, and the flake and coverage policies that keep a suite trustworthy. Use when defining how a codebase is tested.