flutter-offline-first

name flutter-offline-first description Lead authority for offline-first Flutter architecture. Use when designing local-first apps, sync engines, conflict resolution, optimistic UI, retry queues, background sync, or mission-critical apps requiring reliability without connectivity. Flutter Offline-First Skill Purpose Design and implement local-first Flutter architectures that remain fully functional without network connectivity and synchronize reliably when connectivity is restored. Scope and authority Lead authority for: offline-first architectural patterns (local-first, event sourcing, CQRS-lite) sync engine design (bidirectional sync, delta sync) conflict resolution strategies (LWW, CRDT, manual merge) optimistic UI with rollback retry queue design and persistence background sync (WorkManager, Dart isolates) network connectivity awareness Defers to: flutter-storage for persistence layer implementation (Drift, Isar) flutter-networking for remote sync transport (Dio) flutter-state-management for UI state during sync When to use Designing apps for unreliable connectivity (field workers, developing regions) Mission-critical apps requiring offline reliability (medical, logistics, payments) Building collaborative features requiring conflict resolution Designing sync between local and remote state Optimistic updates with network confirmation Offline-first architecture patterns Pattern 1: Repository sync (recommended for most apps) UI → Riverpod Notifier → Repository (single source of truth) ↓ ↑ Local DB (Drift) Remote API (Dio) ↕ Background Sync Service The Repository exposes Streams backed by local data. Remote sync updates the local DB, which reactively updates the Stream, which updates the UI. // Offline-first read: Stream<List<Order>> watchOrders() async* { // 1. Immediately yield local data yield await _localSource.getOrders(); // 2. Sync with remote in background unawaited(_syncOrders()); // 3. Watch local DB for changes (reactive) yield* _localSource.watchOrders(); } Future<void> _syncOrders() async { try { final remoteOrders = await _remoteSource.fetchOrders(); await _localSource.replaceOrders(remoteOrders); } on NetworkException { // Silent fail — UI has local data already _logger.warning('Sync failed — will retry on next foreground'); } } Pattern 2: Optimistic writes with sync queue // Optimistic write: persist locally first, then sync Future<Result<void>> createOrder(Order order) async { // 1. Persist locally immediately (optimistic) final localOrder = order.copyWith( id: _generateLocalId(), syncStatus: SyncStatus.pending, ); await _localSource.insertOrder(localOrder); // 2. Attempt immediate remote sync try { final remoteOrder = await _remoteSource.createOrder(order); // 3a. Mark as synced with remote ID await _localSource.markSynced(localOrder.id, remoteId: remoteOrder.id); return const Result.success(null); } on NetworkException { // 3b. Queue for background retry await _syncQueue.enqueue(SyncTask.createOrder(localOrder.id)); return const Result.success(null); // Optimistic — show success to user } } Pattern 3: Background sync queue (Drift-backed) // Sync queue persisted in local DB — survives app restart @DataClassName('SyncTaskEntry') class SyncQueue extends Table { IntColumn get id => integer().autoIncrement()(); TextColumn get taskType => text()(); TextColumn get payload => text()(); // JSON IntColumn get retryCount => integer().withDefault(const Constant(0))(); DateTimeColumn get nextRetryAt => dateTime().nullable()(); BoolColumn get isProcessing => boolean().withDefault(const Constant(false))(); DateTimeColumn get createdAt => dateTime().withDefault(currentDateAndTime)(); } class SyncQueueService { final SyncQueueDao _dao; final RemoteDataSource _remote; Timer? _syncTimer; void startPeriodicSync({Duration interval = const Duration(minutes: 5)}) { _syncTimer = Timer.periodic(interval, (_) => processQueue()); } Future<void> processQueue() async { final pendingTasks = await _dao.getPendingTasks(limit: 10); for (final task in pendingTasks) { if (task.retryCount >= 5) { await _dao.markFailed(task.id); continue; } try { await _executeTask(task); await _dao.delete(task.id); } catch (e) { // Exponential backoff final nextRetry = DateTime.now().add( Duration(minutes: 1 << task.retryCount), ); await _dao.incrementRetry(task.id, nextRetryAt: nextRetry); } } } void dispose() => _syncTimer?.cancel(); } Conflict resolution strategies Last-Write-Wins (LWW) // Simple: latest timestamp wins ResolvedRecord resolveConflict(LocalRecord local, RemoteRecord remote) { return local.updatedAt.isAfter(remote.updatedAt) ? ResolvedRecord.fromLocal(local) : ResolvedRecord.fromRemote(remote); } When to use: non-collaborative data, simple user preferences, last-edit wins acceptably. Field-level merge (collaborative editing) // Merge non-conflicting field changes ResolvedOrder mergeOrder(LocalOrder local, RemoteOrder remote, BaseOrder base) { return ResolvedOrder( // Field changed on local but not remote: keep local title: local.title != base.title ? local.title : remote.title, // Field changed on remote but not local: keep remote status: remote.status != base.status ? remote.status : local.status, // Both changed: conflict — flag for user resolution assigneeId: (local.assigneeId != base.assigneeId && remote.assigneeId != base.assigneeId) ? null // ConflictMarker : local.assigneeId != base.assigneeId ? local.assigneeId : remote.assigneeId, ); } CRDT (conflict-free replicated data types) Use for collaborative documents, shared lists, counters. Consider automerge-dart for complex collaborative scenarios. Connectivity awareness // core/network/connectivity_service.dart @riverpod Stream<bool> isOnline(Ref ref) async* { final connectivity = Connectivity(); yield await _checkConnectivity(connectivity); yield* connectivity.onConnectivityChanged .map((result) => result != ConnectivityResult.none); } // Repository using connectivity awareness: Future<void> sync() async { final online = await ref.read(isOnlineProvider.future); if (!online) { _logger.info('Offline — skipping sync, queuing for later'); return; } await processQueue(); } Optimistic UI with rollback // Notifier with optimistic update and rollback @riverpod class OrderListNotifier extends _$OrderListNotifier { @override Future<List<Order>> build() async { return ref.watch(orderRepositoryProvider).getOrders(); } Future<void> deleteOrder(String orderId) async { // Save previous state for rollback final previousState = state; // Optimistic update: remove from UI immediately state = AsyncData( state.value!.where((o) => o.id != orderId).toList(), ); try { await ref.read(orderRepositoryProvider).deleteOrder(orderId); } catch (e) { // Rollback on failure state = previousState; // Show error to user ref.read(snackbarProvider.notifier).showError('Failed to delete order'); } } } Sync status indicators (UI pattern) sealed class SyncStatus { const SyncStatus(); } class SyncIdle extends SyncStatus {} class SyncInProgress extends SyncStatus {} class SyncSuccess extends SyncStatus { final DateTime lastSynced; const SyncSuccess(this.lastSynced); } class SyncFailed extends SyncStatus { final String error; final int pendingCount; const SyncFailed({required this.error, required this.pendingCount}); } Anti-pattern detection Remote data fetched in widget build() (no local cache first) No optimistic updates (shows loading spinner for every mutation) Sync queue without retry limits (infinite retry loop) No conflict resolution strategy documented (leads to silent data loss) Background sync without network connectivity check Sync queue not persisted (lost on app restart) No sync status shown to user (they don't know data is stale) Cross-skill handoff payload Use the standard payload from ../../AGENTS.md . Set requesting_skill to flutter-offline-first . Output contract Follow global section order from ../../AGENTS.md . Also include: Offline-first pattern selection and justification Sync architecture diagram Conflict resolution strategy Sync queue design Optimistic update plan Connectivity awareness implementation Related resources references/offline-first-patterns.md references/conflict-resolution.md references/sync-queue-design.md templates/offline-repository.dart templates/sync-queue-service.dart templates/optimistic-notifier.dart