feat(offline): tier 2 phase 1 — Drift cache + read-through for notes

First slice of the tier 2 offline mode work tracked in Fable #147. Notes are the only domain wired so far; this PR establishes the shape and proves the round-trip end-to-end before extending to tasks / projects / events / etc. in phase 2. Local store - Adds drift ^2.20.0 + sqlite3_flutter_libs ^0.5.24 + path ^1.9.0 runtime deps and drift_dev / build_runner dev deps. - New lib/data/local/database.dart: FabledDatabase with CachedNotes (mirroring the Note model 1:1; tags stored as JSON-encoded text) and SyncMetadata (per-domain last_synced_at). Database file lives at $appDocs/fabled_cache.sqlite; opened lazily in a background isolate. - fabledDatabaseProvider on the existing api_client_provider; closes the DB when the ProviderScope disposes. Repository pattern - NotesRepository now takes (NotesApi, FabledDatabase). Reads attempt the network first; on success the response is written to the cache. On NetworkException reads fall back to the cache (rethrowing if it is empty so fresh-install offline still surfaces the network error). - Writes (create/update/delete) hit the server then sync the cache; offline write queueing is phase 3 and explicitly not wired here. - AuthStatus.offline stays owned by AuthNotifier.verify()'s heartbeat; this repo deliberately doesn't poke that state. OfflineBanner - Reads notesRepository.lastSyncedAt(); when present, swaps "Offline — showing cached data." for "Offline — last sync X min ago." A 30s timer refreshes the relative-time string while the banner is mounted. - Falls back to the generic message if no cache exists yet (fresh install offline). Verification - flutter analyze: No issues found Out of scope (later phases per the task body) - Tasks / projects / milestones / events / conversation list / journal day caching (phase 2 — same wrapper pattern, repeated) - Generic write queue with conflict resolution on updated_at (phase 3) - Read-only UI indicators on screens that depend on cached data (phase 4) - Full offline chat (out of scope; needs a local model) - RAG / search over cached content (out of scope) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-28 21:08:06 -04:00
parent b9e68e3bc8
commit 6ef658558a
12 changed files with 1743 additions and 18 deletions
@@ -0,0 +1,152 @@
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:drift/drift.dart';
+import 'package:drift/native.dart';
+import 'package:path/path.dart' as p;
+import 'package:path_provider/path_provider.dart';
+import 'package:sqlite3_flutter_libs/sqlite3_flutter_libs.dart';
+
+import '../models/note.dart';
+
+part 'database.g.dart';
+
+/// Local cache of server-side Notes for offline reads.
+///
+/// Mirrors the shape of [Note] one-to-one. Tags are stored as a JSON-encoded
+/// string because SQLite has no native list type and Drift's typed converters
+/// add ceremony we don't need for a simple read cache. `cachedAt` tracks when
+/// the row was last written from a successful API response.
+class CachedNotes extends Table {
+  IntColumn get id => integer()();
+  TextColumn get title => text()();
+  TextColumn get body => text()();
+  TextColumn get tagsJson => text().withDefault(const Constant('[]'))();
+  TextColumn get noteType => text().withDefault(const Constant('note'))();
+  IntColumn get projectId => integer().nullable()();
+  IntColumn get milestoneId => integer().nullable()();
+  DateTimeColumn get createdAt => dateTime()();
+  DateTimeColumn get updatedAt => dateTime()();
+  DateTimeColumn get cachedAt =>
+      dateTime().clientDefault(() => DateTime.now())();
+
+  @override
+  Set<Column> get primaryKey => {id};
+}
+
+/// Per-domain sync timestamp. Keyed by a short domain string ('notes',
+/// 'tasks', 'projects', 'events', etc.) so the OfflineBanner and any
+/// stale-while-revalidate logic can ask "when did we last fetch this".
+class SyncMetadata extends Table {
+  TextColumn get domain => text()();
+  DateTimeColumn get lastSyncedAt => dateTime()();
+
+  @override
+  Set<Column> get primaryKey => {domain};
+}
+
+const String kSyncDomainNotes = 'notes';
+
+@DriftDatabase(tables: [CachedNotes, SyncMetadata])
+class FabledDatabase extends _$FabledDatabase {
+  FabledDatabase() : super(_openConnection());
+  FabledDatabase.forTesting(super.executor);
+
+  @override
+  int get schemaVersion => 1;
+
+  // ── Notes ────────────────────────────────────────────────────────────────
+
+  Future<List<Note>> getAllNotes() async {
+    final rows = await (select(cachedNotes)
+          ..orderBy([(t) => OrderingTerm.desc(t.updatedAt)]))
+        .get();
+    return rows.map(_noteFromRow).toList();
+  }
+
+  Future<Note?> getNote(int id) async {
+    final row = await (select(cachedNotes)..where((t) => t.id.equals(id)))
+        .getSingleOrNull();
+    return row == null ? null : _noteFromRow(row);
+  }
+
+  /// Replace the entire notes cache with the latest server snapshot.
+  /// Used after a successful `getAll()` so the cache reflects deletions
+  /// (a row that's gone from the server should be gone locally too).
+  Future<void> replaceAllNotes(List<Note> notes) async {
+    await transaction(() async {
+      await delete(cachedNotes).go();
+      if (notes.isNotEmpty) {
+        await batch((b) {
+          b.insertAll(
+            cachedNotes,
+            notes.map(_companionFromNote).toList(),
+          );
+        });
+      }
+      await _setLastSyncIn(kSyncDomainNotes, DateTime.now());
+    });
+  }
+
+  /// Upsert a single note (after a successful create / update / getOne).
+  Future<void> upsertNote(Note note) async {
+    await into(cachedNotes).insertOnConflictUpdate(_companionFromNote(note));
+  }
+
+  Future<void> deleteNote(int id) async {
+    await (delete(cachedNotes)..where((t) => t.id.equals(id))).go();
+  }
+
+  // ── Sync metadata ────────────────────────────────────────────────────────
+
+  Future<DateTime?> getLastSync(String domain) async {
+    final row = await (select(syncMetadata)
+          ..where((t) => t.domain.equals(domain)))
+        .getSingleOrNull();
+    return row?.lastSyncedAt;
+  }
+
+  Future<void> _setLastSyncIn(String domain, DateTime timestamp) {
+    return into(syncMetadata).insertOnConflictUpdate(
+      SyncMetadataCompanion(
+        domain: Value(domain),
+        lastSyncedAt: Value(timestamp),
+      ),
+    );
+  }
+}
+
+CachedNotesCompanion _companionFromNote(Note note) => CachedNotesCompanion(
+      id: Value(note.id),
+      title: Value(note.title),
+      body: Value(note.body),
+      tagsJson: Value(jsonEncode(note.tags)),
+      noteType: Value(note.noteType),
+      projectId: Value(note.projectId),
+      milestoneId: Value(note.milestoneId),
+      createdAt: Value(note.createdAt),
+      updatedAt: Value(note.updatedAt),
+    );
+
+Note _noteFromRow(CachedNote row) => Note(
+      id: row.id,
+      title: row.title,
+      body: row.body,
+      tags: (jsonDecode(row.tagsJson) as List<dynamic>).cast<String>(),
+      noteType: row.noteType,
+      projectId: row.projectId,
+      milestoneId: row.milestoneId,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+    );
+
+LazyDatabase _openConnection() {
+  return LazyDatabase(() async {
+    if (Platform.isAndroid) {
+      await applyWorkaroundToOpenSqlite3OnOldAndroidVersions();
+    }
+    final dir = await getApplicationDocumentsDirectory();
+    final file = File(p.join(dir.path, 'fabled_cache.sqlite'));
+    return NativeDatabase.createInBackground(file);
+  });
+}
@@ -1,12 +1,50 @@
+import '../../core/exceptions.dart';
 import '../api/notes_api.dart';
+import '../local/database.dart';
 import '../models/note.dart';

+/// Notes repository with read-through caching for Tier 2 offline support.
+///
+/// Reads attempt the network first; on success the response is written to
+/// the local Drift cache. On `NetworkException` the read falls back to the
+/// cache (rethrowing if the cache is empty so the UI can show its
+/// fresh-install empty state). Writes (create / update / delete) hit the
+/// server then sync the cache; offline write queueing is Phase 3 work and
+/// not yet wired here — write methods will throw on `NetworkException` in
+/// the meantime.
+///
+/// `AuthStatus.offline` is owned by `AuthNotifier.verify()` (a periodic
+/// heartbeat). This repository deliberately does not poke that state — its
+/// only job is to serve what's cached when the network is unreachable.
 class NotesRepository {
  final NotesApi _api;
-  const NotesRepository(this._api);
+  final FabledDatabase _db;

-  Future<List<Note>> getAll() => _api.getAll();
-  Future<Note> getOne(int id) => _api.getOne(id);
+  const NotesRepository(this._api, this._db);
+
+  Future<List<Note>> getAll() async {
+    try {
+      final notes = await _api.getAll();
+      await _db.replaceAllNotes(notes);
+      return notes;
+    } on NetworkException {
+      final cached = await _db.getAllNotes();
+      if (cached.isEmpty) rethrow;
+      return cached;
+    }
+  }
+
+  Future<Note> getOne(int id) async {
+    try {
+      final note = await _api.getOne(id);
+      await _db.upsertNote(note);
+      return note;
+    } on NetworkException {
+      final cached = await _db.getNote(id);
+      if (cached == null) rethrow;
+      return cached;
+    }
+  }

  Future<Note> create(
    String title,
@@ -14,9 +52,17 @@ class NotesRepository {
    List<String> tags = const [],
    int? projectId,
    String noteType = 'note',
-  }) =>
-      _api.create(title, body,
-          tags: tags, projectId: projectId, noteType: noteType);
+  }) async {
+    final note = await _api.create(
+      title,
+      body,
+      tags: tags,
+      projectId: projectId,
+      noteType: noteType,
+    );
+    await _db.upsertNote(note);
+    return note;
+  }

  Future<Note> update(
    int id,
@@ -26,12 +72,27 @@ class NotesRepository {
    int? projectId,
    bool clearProject = false,
    String noteType = 'note',
-  }) =>
-      _api.update(id, title, body,
-          tags: tags,
-          projectId: projectId,
-          clearProject: clearProject,
-          noteType: noteType);
+  }) async {
+    final updated = await _api.update(
+      id,
+      title,
+      body,
+      tags: tags,
+      projectId: projectId,
+      clearProject: clearProject,
+      noteType: noteType,
+    );
+    await _db.upsertNote(updated);
+    return updated;
+  }

-  Future<void> delete(int id) => _api.delete(id);
+  Future<void> delete(int id) async {
+    await _api.delete(id);
+    await _db.deleteNote(id);
+  }
+
+  /// Last successful `getAll` sync timestamp. Surfaced by the OfflineBanner
+  /// when the network is unreachable so the user knows how stale the
+  /// cached notes list is.
+  Future<DateTime?> lastSyncedAt() => _db.getLastSync(kSyncDomainNotes);
 }
@@ -15,6 +15,7 @@ import '../data/api/projects_api.dart';
 import '../data/api/quick_capture_api.dart';
 import '../data/api/settings_api.dart';
 import '../data/api/tasks_api.dart';
+import '../data/local/database.dart';
 import '../data/repositories/auth_repository.dart';
 import '../data/repositories/chat_repository.dart';
 import '../data/repositories/knowledge_repository.dart';
@@ -60,12 +61,24 @@ final projectsApiProvider = Provider<ProjectsApi>((ref) {
  return ProjectsApi(ref.watch(dioProvider));
 });

+/// Local SQLite cache used by repositories for read-through caching and
+/// offline fallback. Backed by Drift; lives for the lifetime of the
+/// ProviderScope and is closed automatically when the scope disposes.
+final fabledDatabaseProvider = Provider<FabledDatabase>((ref) {
+  final db = FabledDatabase();
+  ref.onDispose(db.close);
+  return db;
+});
+
 final authRepositoryProvider = Provider<AuthRepository>((ref) {
  return AuthRepository(ref.watch(authApiProvider));
 });

 final notesRepositoryProvider = Provider<NotesRepository>((ref) {
-  return NotesRepository(ref.watch(notesApiProvider));
+  return NotesRepository(
+    ref.watch(notesApiProvider),
+    ref.watch(fabledDatabaseProvider),
+  );
 });

 final tasksRepositoryProvider = Provider<TasksRepository>((ref) {
@@ -1,12 +1,15 @@
+import 'dart:async';
+
 import 'package:flutter/material.dart';
 import 'package:lucide_icons/lucide_icons.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';

+import '../providers/api_client_provider.dart';
 import '../providers/auth_provider.dart';

 /// Sticky banner shown when the backend is unreachable. Surfaces a retry
-/// action and reserves space for future "last sync X min ago" messaging once
-/// Tier 2 offline caching lands.
+/// action plus a "last sync X ago" hint when there is cached content to
+/// fall back on (Tier 2 offline mode).
 class OfflineBanner extends ConsumerStatefulWidget {
  const OfflineBanner({super.key});

@@ -16,6 +19,38 @@ class OfflineBanner extends ConsumerStatefulWidget {

 class _OfflineBannerState extends ConsumerState<OfflineBanner> {
  bool _retrying = false;
+  DateTime? _lastSync;
+  Timer? _refreshTimer;
+
+  @override
+  void initState() {
+    super.initState();
+    _loadLastSync();
+    // Refresh the relative-time string every 30s so "5 min ago" rolls
+    // forward without the user having to interact with the banner.
+    _refreshTimer = Timer.periodic(
+      const Duration(seconds: 30),
+      (_) => _loadLastSync(),
+    );
+  }
+
+  @override
+  void dispose() {
+    _refreshTimer?.cancel();
+    super.dispose();
+  }
+
+  Future<void> _loadLastSync() async {
+    if (!mounted) return;
+    try {
+      final ts =
+          await ref.read(notesRepositoryProvider).lastSyncedAt();
+      if (!mounted) return;
+      setState(() => _lastSync = ts);
+    } catch (_) {
+      // Non-critical — banner just won't show the sync hint.
+    }
+  }

  Future<void> _retry() async {
    if (_retrying) return;
@@ -27,12 +62,30 @@ class _OfflineBannerState extends ConsumerState<OfflineBanner> {
    }
  }

+  String? _relativeAgo(DateTime ts) {
+    final diff = DateTime.now().difference(ts);
+    if (diff.isNegative) return null;
+    if (diff.inMinutes < 1) return 'just now';
+    if (diff.inMinutes < 60) return '${diff.inMinutes} min ago';
+    if (diff.inHours < 24) {
+      final h = diff.inHours;
+      return '$h ${h == 1 ? 'hour' : 'hours'} ago';
+    }
+    final d = diff.inDays;
+    return '$d ${d == 1 ? 'day' : 'days'} ago';
+  }
+
  @override
  Widget build(BuildContext context) {
    final status = ref.watch(authProvider);
    if (status != AuthStatus.offline) return const SizedBox.shrink();

    final scheme = Theme.of(context).colorScheme;
+    final ago = _lastSync == null ? null : _relativeAgo(_lastSync!);
+    final message = ago == null
+        ? 'Offline — showing cached data.'
+        : 'Offline — last sync $ago.';
+
    return Material(
      color: scheme.errorContainer,
      child: SafeArea(
@@ -46,7 +99,7 @@ class _OfflineBannerState extends ConsumerState<OfflineBanner> {
              const SizedBox(width: 8),
              Expanded(
                child: Text(
-                  'Offline — showing cached data.',
+                  message,
                  style: TextStyle(color: scheme.onErrorContainer),
                ),
              ),
@@ -9,6 +9,7 @@
 #include <flutter_timezone/flutter_timezone_plugin.h>
 #include <open_file_linux/open_file_linux_plugin.h>
 #include <record_linux/record_linux_plugin.h>
+#include <sqlite3_flutter_libs/sqlite3_flutter_libs_plugin.h>
 #include <url_launcher_linux/url_launcher_plugin.h>

 void fl_register_plugins(FlPluginRegistry* registry) {
@@ -21,6 +22,9 @@ void fl_register_plugins(FlPluginRegistry* registry) {
  g_autoptr(FlPluginRegistrar) record_linux_registrar =
      fl_plugin_registry_get_registrar_for_plugin(registry, "RecordLinuxPlugin");
  record_linux_plugin_register_with_registrar(record_linux_registrar);
+  g_autoptr(FlPluginRegistrar) sqlite3_flutter_libs_registrar =
+      fl_plugin_registry_get_registrar_for_plugin(registry, "Sqlite3FlutterLibsPlugin");
+  sqlite3_flutter_libs_plugin_register_with_registrar(sqlite3_flutter_libs_registrar);
  g_autoptr(FlPluginRegistrar) url_launcher_linux_registrar =
      fl_plugin_registry_get_registrar_for_plugin(registry, "UrlLauncherPlugin");
  url_launcher_plugin_register_with_registrar(url_launcher_linux_registrar);
@@ -6,6 +6,7 @@ list(APPEND FLUTTER_PLUGIN_LIST
  flutter_timezone
  open_file_linux
  record_linux
+  sqlite3_flutter_libs
  url_launcher_linux
 )

@@ -13,6 +13,7 @@ import open_file_mac
 import package_info_plus
 import record_macos
 import shared_preferences_foundation
+import sqlite3_flutter_libs
 import url_launcher_macos

 func RegisterGeneratedPlugins(registry: FlutterPluginRegistry) {
@@ -24,5 +25,6 @@ func RegisterGeneratedPlugins(registry: FlutterPluginRegistry) {
  FPPPackageInfoPlusPlugin.register(with: registry.registrar(forPlugin: "FPPPackageInfoPlusPlugin"))
  RecordMacOsPlugin.register(with: registry.registrar(forPlugin: "RecordMacOsPlugin"))
  SharedPreferencesPlugin.register(with: registry.registrar(forPlugin: "SharedPreferencesPlugin"))
+  Sqlite3FlutterLibsPlugin.register(with: registry.registrar(forPlugin: "Sqlite3FlutterLibsPlugin"))
  UrlLauncherPlugin.register(with: registry.registrar(forPlugin: "UrlLauncherPlugin"))
 }
@@ -57,6 +57,54 @@ packages:
      url: "https://pub.dev"
    source: hosted
    version: "2.1.2"
+  build:
+    dependency: transitive
+    description:
+      name: build
+      sha256: a156715e7cd728130c592f30552575908aae5b100005fbc1f0fb16b3c03a3d10
+      url: "https://pub.dev"
+    source: hosted
+    version: "4.0.6"
+  build_config:
+    dependency: transitive
+    description:
+      name: build_config
+      sha256: "4070d2a59f8eec34c97c86ceb44403834899075f66e8a9d59706f8e7834f6f71"
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.3.0"
+  build_daemon:
+    dependency: transitive
+    description:
+      name: build_daemon
+      sha256: bf05f6e12cfea92d3c09308d7bcdab1906cd8a179b023269eed00c071004b957
+      url: "https://pub.dev"
+    source: hosted
+    version: "4.1.1"
+  build_runner:
+    dependency: "direct dev"
+    description:
+      name: build_runner
+      sha256: "22fdcc3cfeb9d974d7408718c4be15ec5e9b1b350088f3a6c88f154e74dd700d"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.14.1"
+  built_collection:
+    dependency: transitive
+    description:
+      name: built_collection
+      sha256: "376e3dd27b51ea877c28d525560790aee2e6fbb5f20e2f85d5081027d94e2100"
+      url: "https://pub.dev"
+    source: hosted
+    version: "5.1.1"
+  built_value:
+    dependency: transitive
+    description:
+      name: built_value
+      sha256: "0730c18c770d05636a8f945c32a4d7d81cb6e0f0148c8db4ad12e7748f7e49af"
+      url: "https://pub.dev"
+    source: hosted
+    version: "8.12.5"
  characters:
    dependency: transitive
    description:
@@ -65,6 +113,14 @@ packages:
      url: "https://pub.dev"
    source: hosted
    version: "1.4.1"
+  charcode:
+    dependency: transitive
+    description:
+      name: charcode
+      sha256: fb0f1107cac15a5ea6ef0a6ef71a807b9e4267c713bb93e00e92d737cc8dbd8a
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.4.0"
  checked_yaml:
    dependency: transitive
    description:
@@ -153,6 +209,14 @@ packages:
      url: "https://pub.dev"
    source: hosted
    version: "1.0.8"
+  dart_style:
+    dependency: transitive
+    description:
+      name: dart_style
+      sha256: "29f7ecc274a86d32920b1d9cfc7502fa87220da41ec60b55f329559d5732e2b2"
+      url: "https://pub.dev"
+    source: hosted
+    version: "3.1.7"
  dio:
    dependency: "direct main"
    description:
@@ -177,6 +241,22 @@ packages:
      url: "https://pub.dev"
    source: hosted
    version: "2.1.2"
+  drift:
+    dependency: "direct main"
+    description:
+      name: drift
+      sha256: "055c249d1f91be5a47fe447f88afc24c4ca6f4cd6c5ed66767b4797d48acc2e5"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.32.1"
+  drift_dev:
+    dependency: "direct dev"
+    description:
+      name: drift_dev
+      sha256: "88a9de3af8571518148a6d8a513b57779fd1e60a026d3ab8a481a878fba01d91"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.32.1"
  equatable:
    dependency: transitive
    description:
@@ -368,6 +448,14 @@ packages:
      url: "https://pub.dev"
    source: hosted
    version: "8.0.2"
+  graphs:
+    dependency: transitive
+    description:
+      name: graphs
+      sha256: "741bbf84165310a68ff28fe9e727332eef1407342fca52759cb21ad8177bb8d0"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.3.2"
  hooks:
    dependency: transitive
    description:
@@ -657,7 +745,7 @@ packages:
    source: hosted
    version: "3.2.1"
  path:
-    dependency: transitive
+    dependency: "direct main"
    description:
      name: path
      sha256: "75cca69d1490965be98c73ceaea117e8a04dd21217b37b292c9ddbec0d955bc5"
@@ -808,6 +896,22 @@ packages:
      url: "https://pub.dev"
    source: hosted
    version: "2.2.0"
+  pubspec_parse:
+    dependency: transitive
+    description:
+      name: pubspec_parse
+      sha256: "0560ba233314abbed0a48a2956f7f022cce7c3e1e73df540277da7544cad4082"
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.5.0"
+  recase:
+    dependency: transitive
+    description:
+      name: recase
+      sha256: e4eb4ec2dcdee52dcf99cb4ceabaffc631d7424ee55e56f280bc039737f89213
+      url: "https://pub.dev"
+    source: hosted
+    version: "4.1.0"
  record:
    dependency: "direct main"
    description:
@@ -989,6 +1093,14 @@ packages:
    description: flutter
    source: sdk
    version: "0.0.0"
+  source_gen:
+    dependency: transitive
+    description:
+      name: source_gen
+      sha256: ec37cc0e6694374cbef59ed79685572c870a54ede6fa30a3e420feb3adffea02
+      url: "https://pub.dev"
+    source: hosted
+    version: "4.2.3"
  source_map_stack_trace:
    dependency: transitive
    description:
@@ -1013,6 +1125,30 @@ packages:
      url: "https://pub.dev"
    source: hosted
    version: "1.10.2"
+  sqlite3:
+    dependency: transitive
+    description:
+      name: sqlite3
+      sha256: "56da3e13ed7d28a66f930aa2b2b29db6736a233f08283326e96321dd812030f5"
+      url: "https://pub.dev"
+    source: hosted
+    version: "3.3.1"
+  sqlite3_flutter_libs:
+    dependency: "direct main"
+    description:
+      name: sqlite3_flutter_libs
+      sha256: eeb9e3a45207649076b808f8a5a74d68770d0b7f26ccef6d5f43106eee5375ad
+      url: "https://pub.dev"
+    source: hosted
+    version: "0.5.42"
+  sqlparser:
+    dependency: transitive
+    description:
+      name: sqlparser
+      sha256: ab2b467425f1d4f3acfa5fd11a08226f7d6c26ff102c06be1807e1dff34e050b
+      url: "https://pub.dev"
+    source: hosted
+    version: "0.44.3"
  stack_trace:
    dependency: transitive
    description:
@@ -1037,6 +1173,14 @@ packages:
      url: "https://pub.dev"
    source: hosted
    version: "2.1.4"
+  stream_transform:
+    dependency: transitive
+    description:
+      name: stream_transform
+      sha256: ad47125e588cfd37a9a7f86c7d6356dde8dfe89d071d293f80ca9e9273a33871
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.1.1"
  string_scanner:
    dependency: transitive
    description:
@@ -34,11 +34,20 @@ dependencies:
  just_audio: ^0.9.39
  table_calendar: ^3.1.2

+  # Tier 2 offline mode — local SQL store via Drift (sqlite3 under the hood).
+  # Drift was preferred over Hive in the design since the repo already mirrors
+  # well-defined backend schemas (notes/tasks/projects/etc.) one-to-one.
+  drift: ^2.20.0
+  sqlite3_flutter_libs: ^0.5.24
+  path: ^1.9.0
+
 dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^6.0.0
  flutter_launcher_icons: ^0.14.3
+  drift_dev: ^2.20.0
+  build_runner: ^2.4.13

 flutter_launcher_icons:
  android: true
@@ -10,6 +10,7 @@
 #include <flutter_timezone/flutter_timezone_plugin_c_api.h>
 #include <permission_handler_windows/permission_handler_windows_plugin.h>
 #include <record_windows/record_windows_plugin_c_api.h>
+#include <sqlite3_flutter_libs/sqlite3_flutter_libs_plugin.h>
 #include <url_launcher_windows/url_launcher_windows.h>

 void RegisterPlugins(flutter::PluginRegistry* registry) {
@@ -21,6 +22,8 @@ void RegisterPlugins(flutter::PluginRegistry* registry) {
      registry->GetRegistrarForPlugin("PermissionHandlerWindowsPlugin"));
  RecordWindowsPluginCApiRegisterWithRegistrar(
      registry->GetRegistrarForPlugin("RecordWindowsPluginCApi"));
+  Sqlite3FlutterLibsPluginRegisterWithRegistrar(
+      registry->GetRegistrarForPlugin("Sqlite3FlutterLibsPlugin"));
  UrlLauncherWindowsRegisterWithRegistrar(
      registry->GetRegistrarForPlugin("UrlLauncherWindows"));
 }
@@ -7,6 +7,7 @@ list(APPEND FLUTTER_PLUGIN_LIST
  flutter_timezone
  permission_handler_windows
  record_windows
+  sqlite3_flutter_libs
  url_launcher_windows
 )