Offline-First Flutter: Robust Data Sync & Conflict Resolution for SaaS

Introduction & The Problem

• Lost Productivity: Field agents unable to submit reports, sales teams losing critical order data.
• Poor User Experience: Frustration, data entry re-dos, and ultimately, app abandonment.
• Data Inconsistencies: Users working with stale data or creating divergent records that are hard to reconcile.
• Increased Support Costs: Debugging data loss issues and handling user complaints related to connectivity.

The Solution Concept & Architecture

1. Local-First Operations: All user interactions (creating, updating, deleting data) are first committed to a local database on the device. This ensures immediate responsiveness and allows users to continue working without a network.
2. Change Tracking: The local database or a separate mechanism tracks all local modifications (often using a lastModified timestamp or a syncStatus flag).
3. Synchronization Service: A dedicated client-side service periodically attempts to synchronize local changes with the remote backend and pull down new data from the server. This can be triggered manually, on app resume, or via background tasks.
4. Backend API: The server provides endpoints for sending local changes, receiving server changes, and critically, handling potential conflicts.
5. Conflict Resolution: When both client and server have modified the same record independently, a conflict arises. Strategies range from simple (Last-Write-Wins, client-wins, server-wins) to complex (semantic merging, user-driven resolution).

// High-level architecture conceptual diagram
// User interacts with UI
//   | 
//   V
// Local Database (Sqflite/Hive) <---- (Always read/write here first)
//   | 
//   V
// Client-side Sync Service (Riverpod-managed)
//   | 
//   V (Network Available?)
//   +----------------------------+
//   |                            |
//   V                            V
// Backend API (Push Changes)  Backend API (Pull Changes)
//   |                            |
//   V                            V
// Server Database (PostgreSQL/MongoDB)
//   ^                            ^
//   |                            |
//   +----------------------------+
//        Conflict Resolution Logic (Client or Server-side)

Step-by-Step Implementation

dependencies:
  flutter:
    sdk: flutter
  sqflite: ^2.3.0
  path_provider: ^2.1.1
  http: ^1.1.0
  flutter_riverpod: ^2.4.5
  uuid: ^4.2.1 # For generating unique IDs

1. Define the Data Model

// lib/models/todo.dart
import 'package:uuid/uuid.dart';

const Uuid uuid = Uuid();

class Todo {
  final String id;
  String title;
  bool isCompleted;
  DateTime lastModified;
  bool isSynced; // true if synced with backend, false if local change not yet pushed

  Todo({
    required this.id,
    required this.title,
    this.isCompleted = false,
    required this.lastModified,
    this.isSynced = false,
  });

  factory Todo.fromJson(Map<String, dynamic> json) {
    return Todo(
      id: json['id'] as String,
      title: json['title'] as String,
      isCompleted: (json['isCompleted'] as int) == 1,
      lastModified: DateTime.parse(json['lastModified'] as String),
      isSynced: (json['isSynced'] as int) == 1, // Convert int to bool
    );
  }

  Map<String, dynamic> toJson() {
    return {
      'id': id,
      'title': title,
      'isCompleted': isCompleted ? 1 : 0, // Store bool as int
      'lastModified': lastModified.toIso8601String(),
      'isSynced': isSynced ? 1 : 0,
    };
  }

  Todo copyWith({
    String? id,
    String? title,
    bool? isCompleted,
    DateTime? lastModified,
    bool? isSynced,
  }) {
    return Todo(
      id: id ?? this.id,
      title: title ?? this.title,
      isCompleted: isCompleted ?? this.isCompleted,
      lastModified: lastModified ?? this.lastModified,
      isSynced: isSynced ?? this.isSynced,
    );
  }
}

2. Local Database Helper (Sqflite)

// lib/services/database_helper.dart
import 'package:path_provider/path_provider.dart';
import 'package:sqflite/sqflite.dart';
import 'package:path/path.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import '../models/todo.dart';

class DatabaseHelper {
  static final DatabaseHelper _instance = DatabaseHelper._internal();
  factory DatabaseHelper() => _instance;
  DatabaseHelper._internal();

  static Database? _database;

  Future<Database> get database async {
    if (_database != null) return _database!;
    _database = await _initDatabase();
    return _database!;
  }

  Future<Database> _initDatabase() async {
    final documentsDirectory = await getApplicationDocumentsDirectory();
    final path = join(documentsDirectory.path, 'todos.db');
    return await openDatabase(
      path,
      version: 1,
      onCreate: _onCreate,
    );
  }

  Future<void> _onCreate(Database db, int version) async {
    await db.execute(
      '''
      CREATE TABLE todos(
        id TEXT PRIMARY KEY,
        title TEXT,
        isCompleted INTEGER,
        lastModified TEXT,
        isSynced INTEGER
      )
      '''
    );
  }

  Future<int> insertTodo(Todo todo) async {
    final db = await database;
    return await db.insert('todos', todo.toJson(), conflictAlgorithm: ConflictAlgorithm.replace);
  }

  Future<List<Todo>> getTodos() async {
    final db = await database;
    final List<Map<String, dynamic>> maps = await db.query('todos');
    return List.generate(maps.length, (i) { 
      return Todo.fromJson(maps[i]);
    });
  }

  Future<int> updateTodo(Todo todo) async {
    final db = await database;
    return await db.update(
      'todos',
      todo.toJson(),
      where: 'id = ?',
      whereArgs: [todo.id],
    );
  }

  Future<int> deleteTodo(String id) async {
    final db = await database;
    return await db.delete(
      'todos',
      where: 'id = ?',
      whereArgs: [id],
    );
  }

  Future<List<Todo>> getUnsyncedTodos() async {
    final db = await database;
    final List<Map<String, dynamic>> maps = await db.query(
      'todos',
      where: 'isSynced = ?',
      whereArgs: [0], // 0 represents false
    );
    return List.generate(maps.length, (i) {
      return Todo.fromJson(maps[i]);
    });
  }

  Future<void> markTodosAsSynced(List<Todo> todos) async {
    final db = await database;
    final batch = db.batch();
    for (var todo in todos) {
      batch.update(
        'todos',
        todo.copyWith(isSynced: true).toJson(),
        where: 'id = ?',
        whereArgs: [todo.id],
      );
    }
    await batch.commit(noResult: true);
  }

  // Riverpod provider for DatabaseHelper
  static final databaseHelperProvider = Provider((ref) => DatabaseHelper());
}

3. Synchronization Service

// lib/services/sync_service.dart
import 'dart:convert';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:http/http.dart' as http;
import '../models/todo.dart';
import 'database_helper.dart';

class SyncService {
  final DatabaseHelper _databaseHelper;
  final String _backendUrl = 'http://your-backend-api.com/api/todos'; // REPLACE with your backend URL

  SyncService(this._databaseHelper);

  Future<void> synchronizeData() async {
    try {
      print('Starting data synchronization...');
      await _pushChanges();
      await _pullChanges();
      print('Data synchronization complete.');
    } catch (e) {
      print('Synchronization failed: $e');
      // Implement robust error handling (e.g., retry logic, user notification)
    }
  }

  Future<void> _pushChanges() async {
    final unsyncedTodos = await _databaseHelper.getUnsyncedTodos();
    if (unsyncedTodos.isEmpty) {
      print('No unsynced changes to push.');
      return;
    }

    print('Pushing ${unsyncedTodos.length} unsynced todos to backend.');
    final response = await http.post(
      Uri.parse('$_backendUrl/sync-push'),
      headers: {'Content-Type': 'application/json'},
      body: jsonEncode(unsyncedTodos.map((t) => t.toJson()).toList()),
    );

    if (response.statusCode == 200) {
      // Backend successfully processed changes, mark as synced locally
      await _databaseHelper.markTodosAsSynced(unsyncedTodos);
      print('Successfully pushed changes to backend.');
    } else {
      print('Failed to push changes: ${response.statusCode} - ${response.body}');
      // Handle server errors (e.g., partial success, specific conflict responses)
    }
  }

  Future<void> _pullChanges() async {
    // For a real app, you might send a 'last_sync_timestamp' to the backend
    // to only pull changes since the last successful sync.
    final response = await http.get(Uri.parse('$_backendUrl/sync-pull'));

    if (response.statusCode == 200) {
      final List<dynamic> serverData = jsonDecode(response.body);
      final List<Todo> serverTodos = serverData.map((json) => Todo.fromJson(json)).toList();
      final List<Todo> localTodos = await _databaseHelper.getTodos();

      final Map<String, Todo> localMap = {for (var t in localTodos) t.id: t};

      final List<Todo> todosToUpdateLocally = [];
      for (var serverTodo in serverTodos) {
        final localTodo = localMap[serverTodo.id];
        if (localTodo == null) {
          // New todo from server
          todosToUpdateLocally.add(serverTodo.copyWith(isSynced: true));
        } else if (serverTodo.lastModified.isAfter(localTodo.lastModified)) {
          // Server version is newer (Last-Write-Wins simple strategy)
          todosToUpdateLocally.add(serverTodo.copyWith(isSynced: true));
        } else if (localTodo.isSynced == false && localTodo.lastModified.isAfter(serverTodo.lastModified)) {
          // Local change is newer and unsynced, client wins temporarily, will push later
          // For more complex resolution, you might mark for manual review or merge here.
          print('Local change for ${localTodo.id} is newer. Will push later.');
        } else {
          // Either same or server is older, no update needed from server pull
          // Or local is older but already synced, server has latest
        }
      }

      for (var todo in todosToUpdateLocally) {
        await _databaseHelper.insertTodo(todo); // Upsert operation
      }
      print('Successfully pulled ${todosToUpdateLocally.length} changes from backend.');
    } else {
      print('Failed to pull changes: ${response.statusCode} - ${response.body}');
    }
  }

  // Riverpod provider for SyncService
  static final syncServiceProvider = Provider((ref) {
    final dbHelper = ref.watch(DatabaseHelper.databaseHelperProvider);
    return SyncService(dbHelper);
  });
}

4. Riverpod State Management & UI Integration

// lib/providers/todo_provider.dart
import 'package:flutter_riverpod/flutter_riverpod.dart';
import '../models/todo.dart';
import '../services/database_helper.dart';
import '../services/sync_service.dart';

class TodoNotifier extends AsyncNotifier<List<Todo>> {
  late final DatabaseHelper _databaseHelper;
  late final SyncService _syncService;

  @override
  Future<List<Todo>> build() async {
    _databaseHelper = ref.read(DatabaseHelper.databaseHelperProvider);
    _syncService = ref.read(SyncService.syncServiceProvider);
    return _fetchTodos();
  }

  Future<List<Todo>> _fetchTodos() async {
    return await _databaseHelper.getTodos();
  }

  Future<void> addTodo(String title) async {
    state = const AsyncValue.loading();
    final newTodo = Todo(
      id: uuid.v4(),
      title: title,
      lastModified: DateTime.now(),
      isSynced: false, // Mark as unsynced
    );
    await _databaseHelper.insertTodo(newTodo);
    state = AsyncValue.data(await _fetchTodos()); // Refresh state
    ref.read(SyncService.syncServiceProvider).synchronizeData(); // Trigger sync
  }

  Future<void> toggleTodoStatus(Todo todo) async {
    state = const AsyncValue.loading();
    final updatedTodo = todo.copyWith(
      isCompleted: !todo.isCompleted,
      lastModified: DateTime.now(),
      isSynced: false, // Mark as unsynced
    );
    await _databaseHelper.updateTodo(updatedTodo);
    state = AsyncValue.data(await _fetchTodos());
    ref.read(SyncService.syncServiceProvider).synchronizeData();
  }

  Future<void> deleteTodo(String id) async {
    state = const AsyncValue.loading();
    await _databaseHelper.deleteTodo(id);
    state = AsyncValue.data(await _fetchTodos());
    // Deletion sync strategy: push a 'deleted' flag or ID to backend
    // For this example, we assume backend will handle missing IDs appropriately or we push a 'tombstone'
    ref.read(SyncService.syncServiceProvider).synchronizeData();
  }

  Future<void> refreshAndSync() async {
    state = const AsyncValue.loading();
    await _syncService.synchronizeData();
    state = AsyncValue.data(await _fetchTodos());
  }
}

final todoListProvider = AsyncNotifierProvider<TodoNotifier, List<Todo>>(() {
  return TodoNotifier();
});

// lib/main.dart (Simplified UI Example)
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'providers/todo_provider.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  runApp(const ProviderScope(child: MyApp()));
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Offline-First Todos',
      theme: ThemeData(primarySwatch: Colors.blue),
      home: const TodoScreen(),
    );
  }
}

class TodoScreen extends ConsumerWidget {
  const TodoScreen({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final todoListAsync = ref.watch(todoListProvider);
    final todoNotifier = ref.read(todoListProvider.notifier);

    return Scaffold(
      appBar: AppBar(
        title: const Text('Offline-First Todos'),
        actions: [
          IconButton(
            icon: const Icon(Icons.refresh),
            onPressed: () => todoNotifier.refreshAndSync(),
          ),
        ],
      ),
      body: todoListAsync.when(
        data: (todos) => ListView.builder(
          itemCount: todos.length,
          itemBuilder: (context, index) {
            final todo = todos[index];
            return ListTile(
              title: Text(todo.title),
              leading: Checkbox(
                value: todo.isCompleted,
                onChanged: (_) => todoNotifier.toggleTodoStatus(todo),
              ),
              trailing: IconButton(
                icon: const Icon(Icons.delete),
                onPressed: () => todoNotifier.deleteTodo(todo.id),
              ),
              subtitle: Text('Last Modified: ${todo.lastModified.toLocal().toString().split('.')[0]} ${todo.isSynced ? '(Synced)' : '(Unsynced)'}'),
            );
          },
        ),
        loading: () => const Center(child: CircularProgressIndicator()),
        error: (err, stack) => Center(child: Text('Error: $err')),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () async {
          final newTodoTitle = await _showAddTodoDialog(context);
          if (newTodoTitle != null && newTodoTitle.isNotEmpty) {
            todoNotifier.addTodo(newTodoTitle);
          }
        },
        child: const Icon(Icons.add),
      ),
    );
  }

  Future<String?> _showAddTodoDialog(BuildContext context) {
    TextEditingController controller = TextEditingController();
    return showDialog<String>(
      context: context,
      builder: (context) => AlertDialog(
        title: const Text('Add New Todo'),
        content: TextField(
          controller: controller,
          decoration: const InputDecoration(hintText: 'Enter todo title'),
        ),
        actions: [
          TextButton(
            onPressed: () => Navigator.pop(context), // Dismiss
            child: const Text('Cancel'),
          ),
          ElevatedButton(
            onPressed: () => Navigator.pop(context, controller.text), // Return text
            child: const Text('Add'),
          ),
        ],
      ),
    );
  }
}

Optimization & Best Practices

• Incremental Synchronization: Instead of sending all data every time, only synchronize changed records. This requires tracking changes (e.g., a last_synced_at timestamp on the client and server) to reduce payload size and network usage.
• Background Synchronization: For critical updates, leverage Flutter's workmanager package (for Android) or background_fetch (for iOS) to perform periodic syncs even when the app is in the background. Be mindful of platform restrictions and battery consumption.
• Robust Error Handling and Retries: Network requests can fail. Implement exponential backoff for retries to avoid overwhelming the server. Distinguish between transient errors (e.g., network timeout) and permanent errors (e.g., authentication failure).
• Conflict Resolution UI: For complex scenarios where LWW isn't sufficient, provide a UI that allows users to manually resolve conflicts, presenting both versions of the data.
• Data Model Versioning: As your application evolves, your data model might change. Implement schema migrations for your local database (sqflite supports this) and ensure your backend API handles versioning gracefully.
• Security: Ensure that sensitive data is encrypted at rest in the local database and during transit. Implement proper authentication and authorization for your sync API.
• Performance Testing: Test your sync logic with large datasets and slow network conditions to identify bottlenecks.

Business Impact & ROI

• Increased User Engagement & Retention: A consistently functional app, regardless of connectivity, drastically improves user satisfaction, reducing churn and encouraging daily usage. This directly impacts SaaS subscription renewals.
• Enhanced Data Accuracy & Integrity: By providing a clear strategy for conflict resolution, businesses minimize the risk of lost or inconsistent data, leading to better decision-making and operational efficiency.
• Expanded Market Reach: Apps that work reliably offline can serve users in areas with poor internet infrastructure, opening up new geographic markets and customer segments (e.g., rural areas, developing countries, field service operations).
• Improved Workforce Productivity: For enterprise applications, employees can perform tasks like data entry, inspections, or inventory management without interruption, even when disconnected, leading to higher operational efficiency and reduced downtime.
• Reduced Operational Costs: Less data loss means fewer support tickets related to missing or incorrect information, freeing up support teams to focus on higher-value tasks. Reduced network dependency can also subtly decrease backend load for non-real-time operations.
• Competitive Advantage: Offering a superior offline experience differentiates your product in a crowded market, attracting users who prioritize reliability and flexibility.

Conclusion