rely/docs/STORAGE_AND_MIGRATIONS.md

Storage And Migrations

Local Product Store

The product store is abstracted by LocalDataStore.

Implementations:

• HiveLocalDataStore
• SharedPrefsLocalDataStore
• InMemoryLocalDataStore

Provider:

• lib/app/data/storage/local_data_store_provider.dart

Default:

• USE_HIVE_LOCAL_DB=true

Sync Store

The sync queue has a separate store abstraction:

• lib/features/sync/data/storage/sync_state_store.dart
• HiveSyncStateStore
• SharedPrefsSyncStateStore
• InMemorySyncStateStore

This separation is intentional. Product state and sync queue state have different recovery and migration needs.

Migration Behavior

On startup, LocalRepository:

1. Reads the configured product store.
2. If Hive is enabled and empty, attempts to import legacy shared preferences.
3. Writes the migrated data into Hive.
4. Clears the legacy store.
5. Parses LocalDataState.
6. Reconciles reminder schedules.

If stored JSON is invalid, the app falls back to empty seeded state.

SyncQueueRepository follows the same Hive-first import pattern for sync state.

Adding Persisted Fields

Checklist:

1. Add the field to the feature-owned model.
2. Update constructor, field declaration, copyWith, toJson, and fromJson.
3. Use default values or nullable parsing for backward compatibility.
4. Add the field to LocalDataState if it is a new aggregate collection.
5. Update repository operations that should create, update, merge, or delete it.
6. Update merge behavior if the field is person-owned.
7. Update sync payloads if the backend should receive it.
8. Add tests for old JSON and new JSON.

Increase _schemaVersion in LocalRepository only when the migration needs explicit logic or when a stored shape changes in a way that cannot be handled by default parsing.

Data Loss Traps

• Do not remove unknown lists from LocalDataState.fromJson without a migration.
• Do not clear Hive/shared preferences to "fix" parse issues except in tests.
• When deleting a person, check all person-owned collections and source links.
• When merging people, move facts, dates, signals, messages, inbox candidates, reminders, ideas, moments, and source links to the target profile.
• Reminder scheduling is a side effect of repository writes; failures are swallowed by design.

Useful Tests

flutter test test/features/local
flutter test test/features/local/storage
flutter test test/features/sync/storage