forge back up sync 성공 success! 333 저그 백업

# Blueprint: MemoSquare data backup, survival, and recovery

**Purpose:** Hand this document to another Cursor agent (or human architect) so they can **design a similar system** in another app. It describes **how this Flutter app keeps memo data recoverable** across crashes, bad saves, many in-place upgrades, and **some** reinstall scenarios — and where recovery **cannot** be automatic.

**Canonical implementation (this repo):** Dart under `lib/data/`, `lib/services/`, orchestration in `lib/main.dart`.

---

## 1. Why it feels like “rebuild / override still allows backup”

The app does **not** rely on a single store. It uses **layered persistence**:

| Layer | Typical location | Survives in-place app upgrade? | Survives “Delete app” on iOS? |
|--------|------------------|-------------------------------|-------------------------------|
| A. Working copy | `SharedPreferences` (per-app container) | Yes | **No** |
| B. Local safety net | `getApplicationSupportDirectory()` → `memo_data/` | Yes | **No** |
| C. Survival / folder backup | User-visible path (e.g. `Documents/…`, or **iCloud Drive** folder picked in Files) | N/A (not inside app sandbox) | **Often yes** if folder is outside sandbox / synced |
| D. iCloud board file | App’s **iCloud Drive** container (native channel) | Yes (synced) | **Often yes** if iCloud account + container intact |
| E. Google Drive (optional) | User’s Drive file | Yes | Yes (account + file) |
| F. Backup code | User copy/paste (email, Notes, etc.) | N/A | **Yes** (user-owned) |

**Key idea:** An **in-place** install from Xcode / TestFlight / App Store **keeps the same app container**, so layers **A + B** (and prefs-backed trash) remain. That is why frequent **rebuilds that replace the binary without deleting the app** still show the same data.

If the user **deletes the app** on iPhone, **Apple removes the sandbox** — **A and B are gone** unless something already copied data to **C, D, E, or F**.

---

## 2. Architecture snapshot (mental model)

```mermaid
flowchart TB
  subgraph runtime [Runtime UI state]
    UI[Board + editors]
  end

  subgraph primary [Primary persistence]
    Prefs[SharedPreferences: memos, settings, windows, trash JSON]
  end

  subgraph safety [Local safety net - same machine, app container]
    Auto[autosave_latest.json]
    Snap[snapshots / rotating JSON]
    Log[backup_recovery.log + data_guardian_audit.log]
  end

  subgraph escape [Outside sandbox or user-owned]
    Surv[current.json in chosen folder]
    iCloud[iCloud Drive board JSON - native]
    Drive[Google Drive file - optional]
    Code[Base64 backup code - clipboard / text]
  end

  UI -->|debounced persist| Prefs
  UI -->|same payload| Auto
  Auto --> Snap
  UI --> Surv
  UI --> iCloud
  UI --> Drive
  UI --> Code

Single canonical payload shape: A JSON object (and the same structure inside MemoBackupPack) carrying at least: schema, updatedAt, memos[], trash[], settings, windowStates, windowOrder, plus optional appVersion / appBuild. The backup code is that JSON + checksum, Base64-encoded (lib/data/memo_backup_code.dart).

3. Layer A — Primary store (MemoRepository)

• File: lib/data/memo_repository.dart
• Mechanism: Memos are stored as a list of JSON strings under SharedPreferences keys (memo_squares_v2, etc.). Settings, window layout, and related keys are separate prefs entries.
• Migrations: runStartupMigrations() copies legacy v1 keys to v2 without deleting v1, so a reader upgrade does not orphan old data in one shot.
• Empty-list guard: saveMemos(..., allowEmptyOverwrite: false) refuses to write an empty memo list if MemoSafetyNet.findBestRecoveryOffer() still finds a non-empty backup — prevents prefs from wiping the last known good snapshot after a bug or race.

4. Layer B — MemoSafetyNet (autosave + rotating snapshots)

• File: lib/data/memo_safety_net.dart
• Root directory: getApplicationSupportDirectory() + /memo_data/
• Files:
  • autosave_latest.json — latest full-board JSON payload.
  • snapshots/snapshot_<iso-timestamp>.json — time-stamped copies; only the newest N retained (maxRotatingSnapshots, e.g. 5).
• Writes:
  • Serialized queue (_writeQueue): all disk writes for this subsystem run one-after-another to avoid iOS rename/delete races.
  • Atomic write: temp file → verify non-empty → rename over target (with fallback direct write + logging on failure).
• Empty overwrite guard: If the incoming payload parses to zero memos, the writer does not replace a good on-disk backup unless allowEmptyOverwrite is explicitly true (coordinated with “session peak memo count” and one-shot flags in main.dart).
• Recovery picker: findBestRecoveryOffer() scans autosave, all snapshot JSONs, picks the newest valid file that parses to a non-empty memos list. On macOS, also checks legacy paths under ~/Library/Application Support/ for older app names.
• Logging: appendLog → memo_data/backup_recovery.log with AppBuildIdentity tag on each line.

5. Layer C — MemoSurvivalBackupService (“folder backup”)

• File: lib/services/memo_survival_backup_service.dart
• Intent: Mirror the same board JSON to a folder outside the tight sandbox — default e.g. ~/Documents/MemoSquare Backup/current.json on desktop; on iOS the user should pick iCloud Drive (or another writable Documents provider path) via directory picker — not “File Provider Storage” paths that are read-only.
• Behavior:
  • Debounced sync (~800 ms) after onDataChanged() once markReadyForSync() has been called post-bootstrap.
  • Writes current.json via tmp + rename; optional daily snapshot under snapshots/ when the filesystem allows subfolders.
  • Auto-restore on boot: tryAutoRestoreIfLocalEmpty(...) — if local memo count is 0 but current.json has meaningful memos (or trash), returns a MemoBackupPack so main.dart can replay into prefs + trash store before UI settles.
• Platform hint (document in UX): iPhone app delete clears sandbox; survival folder in iCloud is the practical “reinstall recovery” path for layer C.

6. Layer D — Apple iCloud board sync

• File: lib/services/apple_icloud_board_sync.dart
• Mechanism: MethodChannel('appmemo/icloud_board') — native side reads/writes a board JSON file in the iCloud Drive container (path surfaced to user via boardFilePath()).
• Recovery: If local prefs are empty/corrupt and safety net has nothing, _tryRecoveryOfferFromICloud() in main.dart can build a RecoveryOffer from that file — survives reinstall better than container-only autosave when iCloud is available and the file was populated by prior sync.

7. Layer E — Google Drive (optional user sync)

• File: lib/services/google_drive_sync_service.dart (and merge hooks in main.dart)
• Role: Periodic upload + pull merge of remote JSON — another off-device copy when the user enables it. Not required for the core safety-net story but part of the full “belt and suspenders” design.

8. Layer F — Backup code (portable, human-storable)

• Files: lib/data/memo_backup_code.dart, UI MemoDataBackupScreen (from main.dart navigation).
• Encode: MemoBackupCode.encode(MemoBackupPack) → Base64 string with embedded checksum (tamper detection on decode).
• Decode: Strips whitespace, verifies checksum, parses MemoBackupPack.
• Restore modes: Replace-all vs merge (implemented in main.dart handlers).

9. Trash as soft-delete safety

• File: lib/data/memo_trash_store.dart
• Trash entries live in prefs as JSON, with ~30 day retention semantics before permanent purge. Restores merge memos back into the board. This is user recovery, distinct from crash snapshots.

10. Observability — MemoDataGuardian

• File: lib/services/memo_data_guardian.dart
• Role: Append-only data_guardian_audit.log in the same memo_data/ tree with tagged lines for: blocked empty saves, snapshot writes, recovery sources, merge decisions, iCloud failures, etc. Pairs with MemoSafetyNet for post-mortems.

11. Orchestration — boot and persist (main.dart)

Bootstrap order (simplified):

1. MemoRepository.runStartupMigrations()
2. MemoSurvivalBackupService.ensureBootstrapped() (validate/clear broken folder prefs)
3. Load memos/settings/windows/order/trash from prefs
4. If survival pack applies → write back into prefs + trash
5. If memos still empty or load was corrupted → tryFindRecoveryOffer() (safety net), then _tryRecoveryOfferFromICloud()
6. setState with loaded data; _finishDeferredStartup may show “Local backup found” dialog for RecoveryOffer
7. MemoSurvivalBackupService.markReadyForSync() and stage payload after first frame (deferred startup)

Every successful persist path should:

• Save prefs via MemoRepository where appropriate.
• Build one JSON payload (_createBackupPayload / MemoBackupPack) and call MemoRepository.persistSafetyNetPayload → safety net files.
• MemoSurvivalBackupService.stagePayload + onDataChanged() for folder backup.
• Optionally push to iCloud/Drive per user settings.

Guards against “empty board” wiping real data:

• MemoRepository.saveMemos empty guard (prefs vs safety net).
• MemoSafetyNet.writeAutosaveAndRotateSnapshots empty guard (disk vs disk).
• MemoSurvivalBackupService.syncNow empty guard (folder current.json).
• Session peak memo count in main.dart: if the session ever had memos, block persisting an empty list until explicitly allowed (_allowEmptyPersistOnce after user chooses “Start fresh” on recovery dialog).

12. Spec for another agent (“build this pattern elsewhere”)

Minimum viable multi-layer design:

1. Primary store — fast reads/writes (prefs, SQLite, Hive — team choice).
2. Same-device safety net — full export JSON under getApplicationSupportDirectory() (or equivalent), atomic writes, rotating snapshots, non-empty clobber protection.
3. Optional off-sandbox mirror — user-chosen directory or cloud doc; debounced; tmp+rename; auto-restore only when local is provably empty to avoid overwriting intentional clears (this app still allows nuanced cases — study tryAutoRestoreIfLocalEmpty + memoV2KeyPresent).
4. Optional platform cloud — container-based file (iOS/macOS) or backend sync; recovery read when local + safety net fail.
5. Human-portable export — signed or checksummed serialized blob (like backup code) for air-gapped recovery.
6. Soft delete — time-bounded trash in the same backup payload so restores are complete.
7. Audit log — append-only, build-tagged, for support and Data Sentinel-style investigations.
8. Single JSON schema — one toJson / fromJson “pack” used for file export, safety net, folder backup, and optional cloud — avoids incompatible parallel formats.

Non-goals / caveats to document for users:

• No automatic recovery from app delete without C, D, E, or F having been used.
• Parallel installs (different bundle ID) = different container — not the same data unless synced via cloud/export.

13. File index (implementation map)

14. Related product rules (this repo)

• Data Sentinel (.cursorrules): do not ship silent wipes; prefer migrations and recovery.
• Volt (.cursor/rules/volt-battery-efficiency.mdc): debounce persistence; avoid redundant timers; keep safety paths but coalesce writes.

Document generated for cross-agent handoff. Implementation truth remains the Dart sources cited above.