Isar Database

• Use Isar as the primary local database for structured data persistence

• Define collections using @collection annotation with Id field

• Place collection definitions in the data/local/ directory of the relevant feature

• Run dart run build_runner build --delete-conflicting-outputs after modifying collections

Schema Design

• Keep collections focused — one collection per domain entity

• Use @Index annotations for fields queried frequently

• Use @enumerated for enum fields

• Use Links and Backlinks for relationships between collections

• NEVER store derived/computed values — compute them in the domain layer

Migrations

• Isar handles additive schema changes automatically (new fields, new collections)

• For breaking changes (renamed fields, removed fields), write migration logic in the repository

• Version your database schema and check version on app startup

Repository Pattern for Local Data

• Local DataSource wraps all Isar put , get , delete , watch calls

• Repositories orchestrate between remote and local DataSources

• Repositories decide cache-first vs network-first strategy per use case

Offline-First Patterns

• Cache-First: Read from Isar first, fetch from network in background, update Isar on success

• Network-First: Fetch from network, fall back to Isar on failure

• Write-Behind: Write to Isar immediately, sync to server asynchronously (queue pending changes)

• Always show cached data immediately while refreshing in background

Reactive Queries

• Use Isar's watchLazy() or watch() to stream changes to the UI via BLoC

• Wrap Isar watch streams in the repository and expose as Stream<List<DomainModel>>

• Dispose stream subscriptions properly in BLoC close() method

Secure Storage

• Use flutter_secure_storage for sensitive key-value data (tokens, encryption keys)

• Use SharedPreferences ONLY for non-sensitive user preferences (theme, locale, onboarding flags)

• NEVER store passwords, tokens, or secrets in SharedPreferences or plain Isar