Most Flutter applications are built around a simple assumption:

The internet is available.

A typical application works like this:

UI
 ↓
API Request
 ↓
Server
 ↓
Response
 ↓
UI

This architecture works until the user’s network becomes slow, unstable, or completely unavailable.

Then the application starts showing:

Loading...
Network Error
Try Again
No Internet Connection

An offline-first architecture approaches the problem differently.

Instead of treating local storage as a temporary backup, the application treats local data as an important part of its architecture.

A common offline-first flow is:

UI
 ↓
Local Database
 ↓
Display Data Immediately
 ↓
Sync with Server
 ↓
Update Local Database
 ↓
UI Automatically Updates

This allows a Flutter application to remain useful even when connectivity is poor or unavailable.

In this guide, we’ll explore how to design an offline-first Flutter application using repositories, local databases, remote APIs, synchronization, pending operations, conflict handling, connectivity monitoring, and Clean Architecture.

What Is Offline-First Architecture?

Offline-first means designing the application so that its core functionality does not depend on having a continuous internet connection.

Instead of:

UI → API → UI

the architecture becomes closer to:

        Remote API
            ↕
        Sync Engine
            ↕
      Local Database
            ↕
        Repository
            ↕
           UI

The local database becomes extremely important.

The UI can continue reading local data while synchronization happens separately.

Offline-First Is Not the Same as API Caching

This distinction is important.

Caching typically means:

Call API
 ↓
Save Response
 ↓
Reuse Response Temporarily

Offline-first architecture goes further.

It may support:

Read offline
Write offline
Create offline
Update offline
Delete offline
Queue operations
Synchronize later
Resolve conflicts
Track sync status

For example, imagine a task application.

Without internet, the user creates:

Buy groceries

A cache-only architecture might not allow this operation.

An offline-first application can save the task locally:

Local Database

Task:
Buy groceries

Sync Status:
Pending

When internet connectivity returns:

Pending Task
    ↓
Sync Engine
    ↓
POST /tasks
    ↓
Server
    ↓
Local Record Updated
    ↓
Synced

That is a true offline-first workflow.

Why Build an Offline-First Flutter App?

Offline-first architecture can provide several benefits.

Faster startup

The application can display local data immediately instead of waiting for an API request.

Better poor-network experience

Users can continue working when connectivity is unstable.

Reduced loading states

Previously synchronized data is already available locally.

Offline functionality

Depending on the product, users may continue:

Reading content
Creating records
Editing records
Deleting records
Completing forms
Managing tasks

without internet access.

Better perceived performance

Local database reads are usually much faster than remote network requests.

When Should You Use Offline-First?

Offline-first is particularly useful for applications such as:

Field service apps
Delivery applications
Inventory systems
School management apps
Agriculture applications
Task managers
Note-taking apps
Sales applications
Inspection apps
Healthcare field tools
Travel apps
Content applications

It becomes especially valuable when users may operate in areas with unreliable connectivity.

When Offline-First May Be Unnecessary

Not every Flutter application needs full offline-first synchronization.

For example, some applications rely heavily on real-time server state:

Live trading
Payment processing
Live bidding
Real-time multiplayer games
Bank transactions

Local caching can still improve parts of these applications, but allowing offline mutations may not make sense for sensitive operations.

Architecture should follow product requirements.

Recommended Flutter Offline-First Architecture

For a scalable Flutter project, a useful architecture is:

Presentation
     ↓
Domain
     ↓
Repository
   ↙     ↘
Local   Remote
Data    Data
Source  Source
   ↘     ↙
   Sync Engine

In practical terms:

Flutter UI
     ↓
GetX / Bloc / Riverpod
     ↓
Use Case
     ↓
Repository
     ↓
Local Database
     ↕
Sync Manager
     ↕
Remote API

The key principle is:

The UI should not directly decide whether data comes from the API or local database.

That responsibility belongs lower in the architecture.

Recommended Project Structure

A feature-based project could look like:

lib/
│
├── core/
│   ├── api/
│   │   ├── api_client.dart
│   │   ├── api_endpoints.dart
│   │   └── network_info.dart
│   │
│   ├── database/
│   │   ├── local_database.dart
│   │   └── database_tables.dart
│   │
│   ├── sync/
│   │   ├── sync_manager.dart
│   │   ├── sync_operation.dart
│   │   └── sync_status.dart
│   │
│   ├── error/
│   │   ├── exceptions.dart
│   │   └── failures.dart
│   │
│   └── utils/
│       ├── app_constants.dart
│       └── app_utils.dart
│
└── features/
    └── tasks/
        ├── data/
        │   ├── dto/
        │   │   └── task_dto.dart
        │   │
        ├── models/
        │   │   └── task_local_model.dart
        │   │
        ├── data_sources/
        │   │   ├── task_local_data_source.dart
        │   │   └── task_remote_data_source.dart
        │   │
        └── repositories/
        │       └── task_repository_impl.dart
        │
        ├── domain/
        │   ├── entities/
        │   │   └── task_entity.dart
        │   ├── repositories/
        │   │   └── task_repository.dart
        │   └── use_cases/
        │       ├── get_tasks.dart
        │       └── create_task.dart
        │
        └── presentation/
            ├── controllers/
            │   └── task_controller.dart
            ├── screens/
            │   └── task_screen.dart
            └── widgets/
                └── task_card.dart

This keeps remote data, local data, synchronization, domain logic, and presentation separated.

The Local Database as the UI Data Source

One of the most useful offline-first patterns is:

API
 ↓
Repository
 ↓
Local Database
 ↓
UI

Instead of:

API
 ↓
Repository
 ↓
UI

Why?

Suppose the API returns 50 products.

Instead of returning those products directly to the screen:

API → UI

save them locally:

API
 ↓
Local Database
 ↓
UI observes database

When synchronization updates the database, the UI receives the new state.

This creates a consistent source for both online and offline data.

Choosing a Local Database

Flutter offers several options for local persistence.

Common choices include:

Drift / SQLite
Isar
Hive
SharedPreferences

The right choice depends on your data.

For structured relational data such as:

Users
Orders
Products
Students
Classes
Attendance

a database-oriented solution such as SQLite/Drift can be very useful.

For simpler local object storage, other solutions may be sufficient.

SharedPreferences is better suited to small preference-style values than a complete offline-first relational database.

Example Task Entity

Let’s build a simple offline-first task feature.

Our domain entity might be:

class TaskEntity {
  final String id;
  final String title;
  final bool completed;
  final DateTime updatedAt;

  const TaskEntity({
    required this.id,
    required this.title,
    required this.completed,
    required this.updatedAt,
  });
}

The domain does not need to know whether the task came from:

REST API
SQLite
Local cache
Pending sync queue

It simply understands a Task.

Remote DTO

The API may return:

{
  "id": "task_1001",
  "title": "Complete Flutter article",
  "is_completed": false,
  "updated_at": "2026-09-18T09:30:00Z"
}

Create:

class TaskDto {
  final String id;
  final String title;
  final bool isCompleted;
  final DateTime updatedAt;

  const TaskDto({
    required this.id,
    required this.title,
    required this.isCompleted,
    required this.updatedAt,
  });

  factory TaskDto.fromJson(
    Map<String, dynamic> json,
  ) {
    return TaskDto(
      id: json['id'],
      title: json['title'],
      isCompleted: json['is_completed'],
      updatedAt: DateTime.parse(
        json['updated_at'],
      ),
    );
  }
}

The DTO understands the server representation.

Local Model

Your database may need additional information that the API does not provide.

For example:

enum SyncStatus {
  synced,
  pendingCreate,
  pendingUpdate,
  pendingDelete,
  failed,
}

Now:

class TaskLocalModel {
  final String id;
  final String title;
  final bool completed;

  final DateTime updatedAt;

  final SyncStatus syncStatus;

  const TaskLocalModel({
    required this.id,
    required this.title,
    required this.completed,
    required this.updatedAt,
    required this.syncStatus,
  });
}

Notice the additional:

syncStatus

field.

The server does not necessarily need this field.

It exists because the client needs to track synchronization.

Sync Status

A practical offline-first application needs to know whether a local change has reached the server.

For example:

synced
pendingCreate
pendingUpdate
pendingDelete
failed

A new offline task could be:

Task:
Complete Flutter article

Sync Status:
pendingCreate

After synchronization:

Sync Status:
synced

Reading Data Offline

Reading is the easiest offline-first operation.

Instead of:

final response = await dio.get('/tasks');

return response.data;

the repository can first return local data.

Conceptually:

Stream<List<TaskEntity>> watchTasks() {
  return localDataSource
      .watchTasks()
      .map(
        (models) => models
            .map((model) => model.toEntity())
            .toList(),
      );
}

Now the UI observes local data.

Background Synchronization

Separately, the repository can refresh the local database:

Future<void> refreshTasks() async {
  final remoteTasks =
      await remoteDataSource.getTasks();

  await localDataSource.replaceTasks(
    remoteTasks,
  );
}

The complete flow becomes:

Screen Opens
     ↓
Read Local Database
     ↓
Display Immediately
     ↓
Fetch Remote Data
     ↓
Update Local Database
     ↓
UI Updates Automatically

This is much smoother than displaying a full-screen loader on every visit.

Offline-First Repository

A repository might expose:

abstract class TaskRepository {
  Stream<List<TaskEntity>> watchTasks();

  Future<void> refreshTasks();

  Future<void> createTask(
    String title,
  );

  Future<void> updateTask(
    TaskEntity task,
  );

  Future<void> deleteTask(
    String id,
  );

  Future<void> syncPendingChanges();
}

Notice that:

watchTasks()

does not expose whether the underlying source is SQLite, Isar, or another database.

Creating Data While Offline

This is where offline-first becomes more interesting.

Suppose the user has no internet and creates:

Buy groceries

Do not simply show:

No internet.
Try again later.

Instead:

Create Task
    ↓
Generate Local ID
    ↓
Save Locally
    ↓
Mark pendingCreate
    ↓
Update UI
    ↓
Synchronize Later

Generating a Client ID

The server normally generates IDs.

However, an offline application cannot wait for the server.

You can generate a client-side UUID.

For example:

final id = const Uuid().v4();

Then create:

final task = TaskLocalModel(
  id: id,
  title: title,
  completed: false,
  updatedAt: DateTime.now(),
  syncStatus:
      SyncStatus.pendingCreate,
);

Save it immediately.

await localDataSource.insertTask(task);

The UI can display the new task without waiting for the network.

Create Flow

The complete create operation becomes:

User taps Add
      ↓
Generate UUID
      ↓
Insert Local Task
      ↓
pendingCreate
      ↓
UI Updates
      ↓
Internet Available?
   ↙            ↘
 Yes             No
  ↓               ↓
Sync Now       Keep Pending

The user experience remains fast even on poor connections.

Synchronizing Pending Creates

When connectivity becomes available:

Future<void> syncPendingCreates() async {
  final tasks =
      await localDataSource
          .getPendingCreates();

  for (final task in tasks) {
    try {
      final remoteTask =
          await remoteDataSource.createTask(
        task,
      );

      await localDataSource.markSynced(
        localId: task.id,
        remoteTask: remoteTask,
      );
    } catch (_) {
      await localDataSource.markFailed(
        task.id,
      );
    }
  }
}

This is a simplified example.

Production systems usually need retry rules and error classification as well.

Offline Updates

Suppose the user edits:

Buy groceries

to:

Buy groceries today

while offline.

Update the local record immediately:

Task
 ↓
Local Update
 ↓
pendingUpdate
 ↓
UI Updated

Then synchronize later:

pendingUpdate
      ↓
PATCH /tasks/{id}
      ↓
Success
      ↓
synced

The user should not need to wait for the network before seeing their own edit.

Offline Deletes

Deletion requires special handling.

If you immediately remove the record completely, the sync engine may forget that it needs to tell the server to delete it.

One option is a tombstone.

For example:

class TaskLocalModel {
  final String id;

  final bool isDeleted;

  final SyncStatus syncStatus;

  // Other fields...
}

When the user deletes the task:

isDeleted = true
syncStatus = pendingDelete

The normal UI hides it.

However, the sync engine can still find it.

pendingDelete
     ↓
DELETE /tasks/{id}
     ↓
Success
     ↓
Remove Local Record

This pattern prevents lost delete operations.

Sync Queue

For more complex applications, instead of storing synchronization state directly on every model, maintain a dedicated operation queue.

For example:

enum SyncOperationType {
  create,
  update,
  delete,
}

Then:

class SyncOperation {
  final String id;
  final String entityType;
  final String entityId;
  final SyncOperationType type;
  final Map<String, dynamic>? payload;
  final DateTime createdAt;
  final int retryCount;

  const SyncOperation({
    required this.id,
    required this.entityType,
    required this.entityId,
    required this.type,
    required this.createdAt,
    required this.retryCount,
    this.payload,
  });
}

The queue might contain:

1. CREATE task_101
2. UPDATE task_202
3. DELETE task_303

When connectivity returns, the synchronization engine processes the queue.

Why Use a Sync Queue?

Imagine the user performs:

Create Task
Update Profile
Delete Note
Create Order Draft

while offline.

Instead of each feature inventing its own synchronization system, the application can maintain:

Pending Operations Queue
          ↓
      Sync Manager
          ↓
       Backend

This becomes particularly useful in larger applications.

Sync Manager

A simplified manager might look like:

class SyncManager {
  final SyncLocalDataSource local;
  final SyncRemoteDataSource remote;

  bool _isSyncing = false;

  SyncManager({
    required this.local,
    required this.remote,
  });

  Future<void> sync() async {
    if (_isSyncing) {
      return;
    }

    _isSyncing = true;

    try {
      final operations =
          await local.getPendingOperations();

      for (final operation in operations) {
        await _process(operation);
      }
    } finally {
      _isSyncing = false;
    }
  }

  Future<void> _process(
    SyncOperation operation,
  ) async {
    // Handle CREATE, UPDATE and DELETE.
  }
}

The _isSyncing guard prevents multiple synchronization processes from running simultaneously.

Connectivity Monitoring

A Flutter application can monitor connectivity changes and trigger synchronization when connectivity appears to return.

Conceptually:

Offline
  ↓
Connectivity Changed
  ↓
Online
  ↓
Start Sync

However, there is an important distinction:

Having Wi-Fi or mobile connectivity does not guarantee that your API is reachable.

For example:

Connected to Wi-Fi
       ↓
No Internet

or:

Internet Available
       ↓
Your API Server Down

Therefore, connectivity status should be treated as a signal to try synchronization, not proof that synchronization will succeed.

Actual network requests still need proper exception handling.

Do Not Block the UI Waiting for Connectivity

Avoid architecture such as:

if (internetAvailable) {
  return api.getTasks();
} else {
  return database.getTasks();
}

for every read.

A stronger offline-first approach is:

UI always reads local data

Network synchronization happens separately

This reduces branching throughout the application.

Sync on App Startup

When the application starts:

App Start
   ↓
Open Local Database
   ↓
Display Local Data
   ↓
Check Pending Operations
   ↓
Attempt Synchronization
   ↓
Fetch Remote Changes

The user does not need to wait for synchronization before seeing existing local data.

Sync on App Resume

Another useful trigger is when the application returns to the foreground.

For example:

App Background
     ↓
User Returns
     ↓
App Resumed
     ↓
Attempt Sync

This can help refresh data after the application has been inactive.

Do not automatically run heavy synchronization every time without considering throttling.

Manual Sync

Sometimes users should be able to request synchronization manually.

For example:

Pull to Refresh

can trigger:

await syncManager.sync();

The application can then:

Push Local Changes
        +
Fetch Remote Changes

depending on your synchronization strategy.

Push vs Pull Synchronization

Offline synchronization usually involves two directions.

Push

Send local changes to the server.

Local Changes
     ↓
Server

Examples:

pendingCreate
pendingUpdate
pendingDelete

Pull

Download server changes.

Server
  ↓
Local Database

A complete synchronization cycle might therefore be:

1. Push pending local changes

2. Pull remote changes

3. Merge changes

4. Update local database

5. Update sync metadata

The exact order depends on your backend design.

Incremental Synchronization

Downloading the entire database on every sync is inefficient.

Suppose your server has:

100,000 tasks

but only 20 changed since the previous synchronization.

Instead of:

GET /tasks

you might use:

GET /tasks?updated_after=LAST_SYNC_TIME

Then the server returns only changed records.

Conceptually:

Last Sync:
10:00

Next Sync:
11:00

Request:
Give me records changed after 10:00

This is called incremental or delta synchronization.

Sync Cursor

Timestamps can work, but a server-generated cursor is often more reliable.

For example:

{
  "data": [],
  "next_cursor": "sync_98372"
}

Store:

sync_98372

locally.

Next time:

GET /sync?cursor=sync_98372

The server determines which changes occurred after that synchronization point.

This can avoid some problems associated with client clocks.

The Hardest Problem: Conflicts

Consider this situation.

At 10:00, both the server and device contain:

Task Title:
Buy groceries

The device goes offline.

At 10:05, the user changes it locally:

Buy groceries today

Meanwhile, another device changes the server record to:

Buy groceries tomorrow

When the first device reconnects:

Local:
Buy groceries today

Server:
Buy groceries tomorrow

Which one should win?

That is a sync conflict.

Conflict Resolution Strategies

There are several strategies.

Last Write Wins

Whichever update has the latest accepted timestamp/version wins.

Local update: 10:05
Server update: 10:07

Server wins

This is simple but can lose user changes.

Server Wins

Whenever a conflict occurs:

Server version → Local database

This is easy to reason about but may discard offline edits.

Client Wins

Local changes overwrite the server.

Local → Server

This can also destroy changes made elsewhere.

Manual Conflict Resolution

For important data, the user can choose.

For example:

This record was changed on another device.

Local:
Buy groceries today

Server:
Buy groceries tomorrow

Then let the user resolve the conflict.

This is more complex but appropriate for some business applications.

Version-Based Conflict Detection

Instead of relying only on timestamps, your backend can maintain versions.

For example:

{
  "id": "task_1",
  "title": "Buy groceries",
  "version": 7
}

The Flutter app edits version:

and sends:

{
  "title": "Buy groceries today",
  "version": 7
}

If the server is already at:

version 8

it knows the client edited stale data.

The server can return a conflict response rather than silently overwriting version 8.

This provides more reliable conflict detection.

Optimistic UI

Offline-first architecture works very well with optimistic UI.

Instead of:

Tap Complete
     ↓
Wait API
     ↓
Success
     ↓
Update UI

use:

Tap Complete
     ↓
Update Local Database
     ↓
UI Updates Immediately
     ↓
Sync in Background

The application feels faster because the user sees the result immediately.

If synchronization eventually fails permanently, the UI can display an appropriate failed-sync state.

Showing Sync Status in the UI

For applications where synchronization matters, you can expose states such as:

Synced
Waiting to sync
Syncing
Sync failed

For example:

enum SyncStatus {
  synced,
  pending,
  syncing,
  failed,
}

The UI might display:

Saved offline

when a record has not yet reached the server.

This is often better than pretending synchronization succeeded.

Retry Strategy

Network requests can fail temporarily.

Do not necessarily mark an operation as permanently failed after the first error.

For example:

Attempt 1
 ↓
Failed

Wait

Attempt 2
 ↓
Failed

Wait Longer

Attempt 3

This is commonly implemented using exponential backoff.

Conceptually:

1 second
2 seconds
4 seconds
8 seconds
16 seconds

You should also set a maximum retry limit or maximum delay.

Not Every Error Should Be Retried

Consider:

500 Server Error
503 Service Unavailable
Network Timeout

These may be temporary.

But:

400 Invalid Data
401 Authentication Required
403 Permission Denied

often require different handling.

Your sync engine should classify errors rather than retrying everything indefinitely.

Authentication During Offline Sync

Suppose the user created several offline operations.

Later, connectivity returns.

However, the access token has expired.

The flow becomes:

Pending Sync
    ↓
API Request
    ↓
401
    ↓
Refresh Access Token
    ↓
Retry Request
    ↓
Continue Sync

This is why your token-refresh architecture should be implemented below the sync manager, typically in the API networking layer.

Your sync manager should not duplicate authentication-refresh logic.

What If the Refresh Token Has Expired?

Then:

Pending Local Changes
        ↓
Authentication Expired
        ↓
Require Login

Be careful here.

Do not automatically delete pending offline work just because the user’s authentication expired.

Depending on your application’s security requirements, you may preserve pending operations until the user authenticates again.

Then:

Login Successful
      ↓
Resume Sync

This prevents unnecessary loss of offline work.

Prevent Duplicate Synchronization

Imagine synchronization is triggered by:

Connectivity restored
App resumed
Pull-to-refresh
Background task

at nearly the same time.

Without protection:

Sync 1
Sync 2
Sync 3
Sync 4

could run concurrently.

Use a guard:

bool _isSyncing = false;

Future<void> sync() async {
  if (_isSyncing) {
    return;
  }

  _isSyncing = true;

  try {
    await performSync();
  } finally {
    _isSyncing = false;
  }
}

For more advanced systems, use proper synchronization primitives or shared in-flight operations.

Operation Ordering

Imagine the user performs:

1. Create Task
2. Update Task
3. Delete Task

while offline.

Sending:

DELETE
CREATE
UPDATE

would obviously be incorrect.

Some operations depend on previous operations.

Therefore, your sync queue may need to preserve order.

For the same entity:

CREATE
 ↓
UPDATE
 ↓
DELETE

should be processed logically.

Queue Compaction

Sometimes you do not need to send every offline operation.

For example:

CREATE task
UPDATE task
UPDATE task
UPDATE task

before synchronization.

Instead of four API calls, you may be able to reduce this to:

CREATE task with latest data

Similarly:

CREATE task
DELETE task

before either reaches the server may sometimes be reduced to:

Nothing

because the server never knew the object existed.

This optimization is called queue compaction.

It can significantly reduce synchronization traffic.

Local IDs vs Server IDs

Offline-created objects need IDs before reaching the server.

There are two common approaches.

Client-generated UUID

Flutter generates UUID
        ↓
Server accepts same UUID

This is one of the cleanest approaches when your backend supports it.

Temporary local ID

local_123
   ↓
POST Server
   ↓
Server returns 9876
   ↓
Replace/Map ID

The second approach requires maintaining a mapping between local and remote identifiers.

When possible, client-generated globally unique IDs can simplify offline architecture considerably.

Relationships Make Offline Sync Harder

Suppose the user creates an order offline.

Order
 ↓
Order Items

The order and its items have relationships.

If the server generates IDs, you may need:

Create Order
    ↓
Receive Server Order ID
    ↓
Map Local ID → Server ID
    ↓
Create Order Items

This is why offline-first systems should be considered during backend API design, not added only at the Flutter UI layer.

Transactions in the Local Database

When multiple local changes belong together, use database transactions where supported.

For example:

Create Order
+
Create 5 Order Items

You do not want:

Order saved
2 items saved
App crashes
3 items missing

A transaction can ensure that either:

Everything succeeds

or:

Nothing is committed

This helps maintain local data consistency.

Pagination in Offline-First Apps

Pagination needs additional thought.

Online:

Page 1
Page 2
Page 3

Offline, the local database may already contain records from several pages.

Instead of making the UI depend on API page numbers, you can often query the local database directly:

Local Database
     ↓
LIMIT 20
OFFSET 0

while the sync layer separately handles remote pagination.

This separates:

UI Pagination

from:

Network Pagination

which can simplify the presentation layer.

Search in Offline-First Apps

Offline search can query the local database.

Instead of:

Search
 ↓
API

you can use:

Search
 ↓
Local Database

when appropriate.

For example:

"flutter"
    ↓
SELECT matching local records

When online, the application can optionally combine local results with remote search depending on product requirements.

Background Synchronization

Some applications benefit from synchronization while the app is not actively being used.

However, background execution differs between Android and iOS and is controlled by operating-system restrictions.

Therefore, background synchronization should be treated as an optimization.

Your application should still synchronize reliably when:

App starts
App resumes
Connectivity returns
User manually refreshes

Do not design the entire system assuming background execution will always happen exactly when requested.

Sync Metadata

A robust local record may contain fields such as:

id
serverId
createdAt
updatedAt
syncStatus
version
isDeleted
lastSyncAttempt
retryCount

For example:

class SyncMetadata {
  final String status;
  final int retryCount;
  final DateTime? lastAttemptAt;
  final int? serverVersion;

  const SyncMetadata({
    required this.status,
    required this.retryCount,
    this.lastAttemptAt,
    this.serverVersion,
  });
}

Metadata helps the sync engine make better decisions.

Offline-First with GetX

If you use GetX, the controller should not contain synchronization internals.

Avoid:

if (internetAvailable) {
  await api.getTasks();
} else {
  await database.getTasks();
}

inside every controller.

Instead:

class TaskController extends GetxController {
  final TaskRepository repository;

  TaskController(this.repository);

  final tasks = <TaskEntity>[].obs;

  @override
  void onInit() {
    super.onInit();

    repository.watchTasks().listen(
      (items) {
        tasks.assignAll(items);
      },
    );

    repository.refreshTasks();
  }
}

The controller observes application data.

The repository handles its origin and synchronization.

Better Data Flow with GetX

A clean flow becomes:

TaskScreen
    ↓
TaskController
    ↓
TaskRepository
    ↓
Local Database
    ↑
Sync Manager
    ↕
Remote API

When the local database changes:

Database Update
      ↓
Stream / Listener
      ↓
Controller
      ↓
Obx
      ↓
UI Rebuild

This makes the UI reactive without coupling it directly to the network.

Offline-First and API Caching Together

Offline-first and caching are not mutually exclusive.

You can use:

Memory Cache
     ↓
Local Database
     ↓
Remote API

For example:

Frequently Accessed Object
         ↓
Memory Cache

Persistent Application Data
         ↓
Local Database

Authoritative Shared Data
         ↓
Remote Server

Each layer solves a different problem.

Source of Truth

A critical architectural decision is determining your application’s source of truth.

For a strong offline-first architecture, this is often:

Local Database

for UI state.

The server remains authoritative for shared remote state, but the UI observes the synchronized local representation.

Therefore:

Server
 ↓
Sync
 ↓
Local Database
 ↓
UI

and:

User Action
 ↓
Local Database
 ↓
UI
 ↓
Sync
 ↓
Server

This gives the application consistent behavior regardless of connectivity.

Server Support Matters

A truly reliable offline-first application cannot always be built entirely on the Flutter side.

The backend should ideally support concepts such as:

Client-generated IDs
Updated timestamps
Record versions
Idempotency
Incremental synchronization
Deletion markers
Conflict detection
Sync cursors

If your backend provides only basic CRUD endpoints, offline synchronization is still possible, but advanced conflict handling becomes more difficult.

Idempotency

Suppose Flutter sends:

Create Order

The server creates the order successfully.

Before Flutter receives the response, the network disconnects.

The client does not know whether creation succeeded.

It retries:

Create Order

Without protection, the server could create two orders.

An idempotency key can help.

For example:

Idempotency-Key:
order-550e8400

If the same operation is retried, the backend recognizes it as the same logical request.

This is particularly important for:

Orders
Bookings
Payments
Reservations
Other sensitive create operations

Deletion Synchronization

Deletes need special consideration during pull synchronization too.

Suppose Device A deletes a task.

Device B is offline.

Later Device B requests:

Give me records changed since last sync

If deleted records simply disappear from the server database, Device B may never know that the task was deleted.

One solution is server-side tombstones.

For example:

{
  "id": "task_101",
  "deleted": true,
  "updated_at": "..."
}

Device B receives this change and removes the local task.

Database Migrations

Offline-first apps store important structured data locally.

As your app evolves:

Version 1
Task:
id
title

Version 2
Task:
id
title
completed

Version 3
Task:
id
title
completed
version
syncStatus

your database schema changes.

You need migration strategies that preserve existing user data.

Never assume users will reinstall the application whenever your database structure changes.

Testing Offline-First Architecture

Offline functionality requires more testing than normal API-driven screens.

Important scenarios include:

App starts offline

Read cached/local data

Create while offline

Update while offline

Delete while offline

Reconnect

Sync pending operations

API timeout

Authentication expiration during sync

App closes during sync

Multiple sync triggers

Conflict between devices

Duplicate create retry

Server error

Invalid local operation

Database migration

These scenarios should be tested deliberately.

Example Offline Test

A repository test might verify:

test(
  'creates task locally when offline',
  () async {
    await repository.createTask(
      'Learn Flutter',
    );

    final localTask =
        await localDataSource
            .findTaskByTitle(
      'Learn Flutter',
    );

    expect(
      localTask.syncStatus,
      SyncStatus.pendingCreate,
    );
  },
);

Another test can verify synchronization:

test(
  'syncs pending task when network returns',
  () async {
    // Arrange pending task.

    await syncManager.sync();

    // Verify remote create called.
    // Verify local task marked synced.
  },
);

Common Offline-First Mistakes

Treating cache as offline-first

Saving an API response locally is caching.

True offline-first architecture may also need local writes and synchronization.

Calling the API directly from controllers

This makes offline behavior difficult to centralize.

Prefer:

Controller → Repository

Trusting connectivity status completely

Wi-Fi connection does not guarantee API availability.

Always handle real request failures.

Deleting offline records immediately

You may lose the information required to synchronize the delete.

Use pending deletes or tombstones when needed.

No conflict strategy

Eventually, multiple devices can edit the same record.

Define how conflicts are detected and resolved.

Retrying forever

Classify errors and limit retries.

Running multiple sync engines simultaneously

Protect synchronization from duplicate execution.

Ignoring operation order

Create/update/delete dependencies matter.

Using server-only IDs

Offline-created records need a usable local identity.

Making the UI wait for synchronization

Offline-first UI should generally react to local state immediately.

Recommended Offline-First Strategy

For many Flutter applications, a strong architecture is:

                 Flutter UI
                     ↓
              State Management
                     ↓
                 Repository
                     ↓
              Local Database
                 ↑       ↓
                 │    Local Writes
                 │
             Sync Engine
               ↕
             REST API

For reads:

UI
 ↓
Local DB
 ↓
Immediate Data

Meanwhile:

API
 ↓
Sync
 ↓
Local DB
 ↓
UI Updates

For writes:

User Action
 ↓
Local DB
 ↓
Mark Pending
 ↓
UI Updates Immediately
 ↓
Sync Engine
 ↓
Server
 ↓
Mark Synced

This provides a consistent mental model for the entire application.

Production Sync Flow

A more complete synchronization cycle might be:

Sync Trigger
    ↓
Check Authentication
    ↓
Push Pending Creates
    ↓
Push Pending Updates
    ↓
Push Pending Deletes
    ↓
Pull Remote Changes
    ↓
Resolve Conflicts
    ↓
Update Local Database
    ↓
Store New Sync Cursor
    ↓
Mark Operations Synced
    ↓
Notify UI

If something fails:

Temporary Error
      ↓
Retry Later

Authentication Error
      ↓
Refresh Token / Login

Conflict
      ↓
Apply Conflict Policy

Permanent Validation Error
      ↓
Mark Operation Failed

Offline-First Best Practices

When building a production Flutter offline-first application:

Keep the UI dependent on repositories rather than APIs.
Consider making the local database the observable source for UI data.
Save user changes locally before synchronization where product rules allow it.
Track pending create, update, and delete operations.
Generate reliable client-side IDs for offline-created objects.
Prevent multiple synchronization jobs from running simultaneously.
Define conflict-resolution rules before production.
Use version numbers or server-controlled sync metadata where possible.
Support incremental synchronization instead of downloading everything repeatedly.
Preserve offline work when temporary authentication or networking failures occur.
Use retry limits and backoff for transient failures.
Do not blindly retry permanent errors.
Consider idempotency for important create operations.
Use database transactions for related local writes.
Test app termination and restart during synchronization.
Handle local database migrations carefully.
Treat connectivity information as a hint, not proof of server availability.
Keep authentication refresh inside the networking layer.
Design the backend with synchronization requirements in mind.
Clearly communicate pending or failed synchronization when users need to know.

API Caching vs Offline-First Architecture

Finally, remember the difference.

API Caching	Offline-First
Reuses previous responses	Works around local data
Mainly improves performance	Improves resilience and functionality
Usually focused on reads	Can support reads and writes
Cache may expire and disappear	Local database can be core app state
Simple invalidation	Requires synchronization
Conflict handling rarely needed	Conflict handling may be essential
Limited offline capability	Designed for offline usage
Easier to implement	More architectural complexity

For a simple content application, API caching may be enough.

For applications where users must continue working without reliable connectivity, offline-first architecture is much more powerful.

Final Thoughts

A Flutter offline-first architecture is not simply:

if internet:
    API
else:
    cache

A stronger architecture is:

                 SERVER
                    ↕
               SYNC ENGINE
                    ↕
              LOCAL DATABASE
                    ↕
                REPOSITORY
                    ↕
             STATE MANAGEMENT
                    ↕
                   UI

The UI primarily works with local application state.

When the user creates or edits something:

User Action
    ↓
Local Database
    ↓
UI Updates Immediately
    ↓
Pending Sync
    ↓
Server

When remote data changes:

Server
   ↓
Synchronization
   ↓
Local Database
   ↓
UI Automatically Updates

That separation is what makes an application truly resilient to unreliable networks.

For production applications, the hardest parts are not storing data locally. The real challenges are synchronization, conflict resolution, operation ordering, idempotency, authentication during sync, and deciding which system owns the authoritative version of each record.

Once those rules are clearly defined, Flutter’s repository pattern, local database layer, reactive state management, and networking layer can work together to provide a fast and reliable offline-first experience.

Flutter Offline-First Architecture: Complete Guide

What Is Offline-First Architecture?

Offline-First Is Not the Same as API Caching

Why Build an Offline-First Flutter App?

Faster startup

Better poor-network experience

Reduced loading states

Offline functionality

Better perceived performance

When Should You Use Offline-First?

When Offline-First May Be Unnecessary

Recommended Flutter Offline-First Architecture

Recommended Project Structure

The Local Database as the UI Data Source

Choosing a Local Database

Example Task Entity

Remote DTO

Local Model

Sync Status

Reading Data Offline

Background Synchronization

Offline-First Repository

Creating Data While Offline

Generating a Client ID

Create Flow

Synchronizing Pending Creates

Offline Updates

Offline Deletes

Sync Queue

Why Use a Sync Queue?

Sync Manager

Connectivity Monitoring

Do Not Block the UI Waiting for Connectivity

Sync on App Startup

Sync on App Resume

Manual Sync

Push vs Pull Synchronization

Push

Pull

Incremental Synchronization

Sync Cursor

The Hardest Problem: Conflicts

Conflict Resolution Strategies

Last Write Wins

Server Wins

Client Wins

Manual Conflict Resolution

Version-Based Conflict Detection

Optimistic UI

Showing Sync Status in the UI

Retry Strategy

Not Every Error Should Be Retried

Authentication During Offline Sync

What If the Refresh Token Has Expired?

Prevent Duplicate Synchronization

Operation Ordering

Queue Compaction

Local IDs vs Server IDs

Client-generated UUID

Temporary local ID

Relationships Make Offline Sync Harder

Transactions in the Local Database

Pagination in Offline-First Apps

Search in Offline-First Apps

Background Synchronization

Sync Metadata

Offline-First with GetX

Better Data Flow with GetX

Offline-First and API Caching Together

Source of Truth

Server Support Matters

Idempotency

Deletion Synchronization

Database Migrations

Testing Offline-First Architecture

Example Offline Test

Common Offline-First Mistakes

Treating cache as offline-first

Calling the API directly from controllers

Trusting connectivity status completely