Flutter offline-first architecture with SQLite and background sync
Network-first apps fail silently in emerging markets and high-mobility environments. This is the complete architecture for an offline-first Flutter app: SQLite as the system of record, a sync engine with conflict resolution, and a UI that never lies about data freshness.
An app that requires a network connection to show a customer their own order history is not a mobile app — it is a website wrapped in a webview. In markets where connectivity drops mid-session, offline capability is not a luxury feature; it is the difference between a usable product and an abandoned download. This is the architecture we use for offline-first Flutter apps, built from shipping products on the global device fleet.
The core principle: local database is the source of truth
The UI reads exclusively from SQLite. It never reads from an API response directly. The sync engine writes API responses into SQLite, and the UI reacts to database changes via streams. The app always has something to render, is never blocked on a network timeout, and user interactions feel instant.
// Repository pattern — UI reads only from local SQLite
class OrderRepository {
final Database _db;
final OrderSyncEngine _sync;
Stream<List<Order>> watchOrders(String customerId) {
return _db
.watchTable('orders')
.where((rows) => rows.where((r) => r['customer_id'] == customerId))
.map((rows) => rows.map(Order.fromMap).toList());
}
Future<void> refresh(String customerId) async {
await _sync.pullOrders(customerId);
}
}The sync engine: pull then push
The sync sequence is always: pull server changes first, apply them locally, then push local dirty rows. This ordering prevents a dirty local write from overwriting a concurrent server change. Each push sends a last_known_server_timestamp header so the server can detect conflicts with HTTP 409 status.
Offline-first is an architecture commitment, not a feature flag. The database is the product; the network is a sync channel. Build it this way from the first migration and you will never need to rewrite it.
Field notes authored by the core engineering and systems team at Chimbuk. We build and maintain production Flutter mobile applications, Next.js web architectures, and cloud backends. No recycled marketing theory — only architecture decisions, code patterns, and performance budgets from real production deployments.
Continue Reading
Related Engineering Guides
We architect and build the systems we write about.
From vector search pipelines to high-concurrency payment gateways — schedule a technical discovery call.