Reference: Offline-First Field App

A composite reference for offline-first field operations - utility inspections, warehouse audits, or municipal asset surveys. Technicians capture photos, GPS fixes, and checklist answers without reliable connectivity. Stack: Expo SDK 57 (expo ~57.0.4), React Native 0.86.0, React 19.2.3.

Context

Operational reality:

40% of work happens in basements, substations, and rural sites with no signal for hours.
Losing a completed inspection because the app crashed before sync is a contract failure, not a UX annoyance.
Devices are rugged Android (Zebra TC57, Honeywell CT40) plus a minority of corporate iPhones.
Backend accepts REST batch uploads; conflict policy is server-authoritative on approval timestamps.

Team constraints: Four mobile engineers, one backend engineer, no on-call native specialist. Expo managed workflow with EAS internal distribution to fleet devices.

Architecture

┌──────────────────────────────────────────────────────────────────────────┐
│                    Field app - offline-first data plane                   │
├──────────────────────────────────────────────────────────────────────────┤
│  Expo Router                                                             │
│    (app)/jobs/[jobId]/inspection/[id]   ← deep link from dispatch SMS    │
├──────────────────────────────────────────────────────────────────────────┤
│  UI layer                                                                │
│    DataFreshnessLabel (live|stale|syncing|unavailable)                   │
│    Optimistic save → SQLite immediately                                  │
├──────────────────────────────────────────────────────────────────────────┤
│  expo-sqlite (source of truth)                                           │
│    inspections, answers, attachments_meta                                │
│    outbox (mutation queue, idempotency_key, payload_json)                │
│    sync_cursor (last_server_seq)                                         │
├──────────────────────────────────────────────────────────────────────────┤
│  TanStack Query                                                          │
│    job list / reference data - stale-while-revalidate when online          │
├──────────────────────────────────────────────────────────────────────────┤
│  NetInfo → onlineManager + foreground flush                              │
│  expo-background-task → deferred outbox drain (≥15 min interval)         │
├──────────────────────────────────────────────────────────────────────────┤
│  expo-file-system + expo-image                                           │
│    attachment files on disk; upload in background worker                 │
└──────────────────────────────────────────────────────────────────────────┘

Write path (offline create):

User taps Save → SQLite INSERT (synced=0) → outbox INSERT
  → UI shows "Pending upload" → (later) NetInfo online
  → flushOutbox() → POST /inspections + Idempotency-Key
  → server ack → UPDATE synced=1, tombstone outbox row

Sync path (background safety net):

OS schedules BACKGROUND_SYNC_TASK
  → open SQLite → flushOutbox (max 50 rows, 25 MB attachments)
  → return Success | Failed

Boot gate in root _layout.tsx runs PRAGMA user_version migrations before any screen reads tables - see expo-sqlite.

Related: Offline-First Basics - connectivity assumptions and UX contract

Recipe

Quick-reference stack card for field capture on SDK 57.

npx create-expo-app@latest FieldInspect --template default@sdk-57
npx expo install expo-sqlite expo-background-task expo-task-manager \
  @react-native-community/netinfo @tanstack/react-query expo-file-system expo-image

// src/sync/outboxFlush.ts (excerpt)
export async function flushOutbox(db: SQLiteDatabase) {
  const rows = await db.getAllAsync<OutboxRow>(
    `SELECT * FROM outbox ORDER BY created_at LIMIT 50`
  );
  for (const row of rows) {
    const res = await api.post("/inspections", row.payload_json, {
      headers: { "Idempotency-Key": row.idempotency_key },
    });
    if (res.ok) await markSynced(db, row.id);
  }
}

// index.ts - register background task in global scope
import "./src/background/syncTask";
import "expo-router/entry";

Device lab minimum: One rugged Android on Android 11+, one iPhone two generations behind current, both on release builds - not Expo Go.

Decisions Made

#	Decision	Choice	Rationale
1	Local source of truth	expo-sqlite with WAL	Relational inspections + outbox; not AsyncStorage blobs - expo-sqlite
2	Server snapshots	TanStack Query for job catalog	Reference lists can be stale; capture data cannot - Sync Strategies
3	Conflict policy	Server-authoritative on `approved_at`	Inspector edits after supervisor approval are discarded with audit note in UX
4	Mutation replay	Outbox + Idempotency-Key	Reconnect must not duplicate rows - Data Layer Best Practices #19–20
5	Background upload	expo-background-task supplement	Foreground flush on NetInfo is primary - Background Sync & TaskManager
6	Attachments	FileSystem paths in SQLite meta	Upload worker streams files; DB stores `local_path`, `remote_url`, `bytes_uploaded`
7	UX contract	Four visible states	Technicians trust "Pending upload" over silent failure - Offline-First Basics #2
8	Rugged testing	Physical Zebra on internal track	Scanner intents and battery saver modes do not exist on emulators - Android Basics for RN Devs
9	OTA scope	JS-only fixes on `production` channel	Schema migrations ship with store builds when `user_version` bumps

Rejected alternatives:

CRDT for checklist answers - backend had no merge engine; server-authoritative simpler for compliance.
Background sync as only path - 15-minute minimum interval missed dispatch deadline; foreground flush mandatory.
AsyncStorage outbox - 200+ pending items after multi-day outage exceeded comfortable JSON size.

Outcomes

Pilot fleet: 120 rugged devices on Android 11–14, SDK 57 build 1.6.0.

Metric	Before (online-first prototype)	After (SQLite + outbox)
Lost submissions / week	11 (user-reported)	0 in 8-week pilot
Median save latency offline	N/A (blocked spinner)	<80ms local commit
Sync within 5 min of connectivity	62%	94%
Background task success rate	-	78% (iOS stricter than Android)
Support tickets: "frozen app"	23/month	4/month

Corruption recovery: one device with a failed OTA mid-migration triggered safeParse quarantine - app rendered last-known-good inspections without white-screening per Data Layer Best Practices #13.

Lessons

SQLite migrations before first paint. A user_version bump shipped in an OTA without a store build bricked cold start once - now native schema changes require binary bump.
Show pending state per row, not global spinner. Inspectors work on job B while job A uploads; per-row synced flag beat a blocking modal.
Rugged devices lie about battery. BatterySaver on Zebra delayed background tasks; document that foreground flush is the real delivery path.
Photo uploads need byte progress. expo-file-system upload with onUploadProgress reduced "did it save?" calls to dispatch.
Logout clears all layers. Stale inspection cache on shared devices was a privacy incident class - queryClient.clear() + SQLite user tables + attachment dirs.
Pin SDK 57 in runbooks. Field IT installs APKs months later; support docs must state which runtimeVersion accepts which OTA.

Offline-First Basics - UX contract and NetInfo
expo-sqlite - WAL, migrations, transactions
Sync Strategies - server reconciliation
Optimistic UI - rollback patterns
Background Sync & TaskManager - deferred flush
expo-image - attachment thumbnails and cache
Network Failure UX - banners and retry copy
Internal Distribution - fleet APK delivery

Stack versions: This page was written for React 19.2.3, React Native 0.86.0, and Expo SDK 57 (expo ~57.0.4).

Context

Operational reality:

40% of work happens in basements, substations, and rural sites with no signal for hours.
Losing a completed inspection because the app crashed before sync is a contract failure, not a UX annoyance.
Devices are rugged Android (Zebra TC57, Honeywell CT40) plus a minority of corporate iPhones.
Backend accepts REST batch uploads; conflict policy is server-authoritative on approval timestamps.

Team constraints: Four mobile engineers, one backend engineer, no on-call native specialist. Expo managed workflow with EAS internal distribution to fleet devices.

Architecture

┌──────────────────────────────────────────────────────────────────────────┐
│                    Field app - offline-first data plane                   │
├──────────────────────────────────────────────────────────────────────────┤
│  Expo Router                                                             │
│    (app)/jobs/[jobId]/inspection/[id]   ← deep link from dispatch SMS    │
├──────────────────────────────────────────────────────────────────────────┤
│  UI layer                                                                │
│    DataFreshnessLabel (live|stale|syncing|unavailable)                   │
│    Optimistic save → SQLite immediately                                  │
├──────────────────────────────────────────────────────────────────────────┤
│  expo-sqlite (source of truth)                                           │
│    inspections, answers, attachments_meta                                │
│    outbox (mutation queue, idempotency_key, payload_json)                │
│    sync_cursor (last_server_seq)                                         │
├──────────────────────────────────────────────────────────────────────────┤
│  TanStack Query                                                          │
│    job list / reference data - stale-while-revalidate when online          │
├──────────────────────────────────────────────────────────────────────────┤
│  NetInfo → onlineManager + foreground flush                              │
│  expo-background-task → deferred outbox drain (≥15 min interval)         │
├──────────────────────────────────────────────────────────────────────────┤
│  expo-file-system + expo-image                                           │
│    attachment files on disk; upload in background worker                 │
└──────────────────────────────────────────────────────────────────────────┘

Write path (offline create):

User taps Save → SQLite INSERT (synced=0) → outbox INSERT
  → UI shows "Pending upload" → (later) NetInfo online
  → flushOutbox() → POST /inspections + Idempotency-Key
  → server ack → UPDATE synced=1, tombstone outbox row

Sync path (background safety net):

OS schedules BACKGROUND_SYNC_TASK
  → open SQLite → flushOutbox (max 50 rows, 25 MB attachments)
  → return Success | Failed

Boot gate in root _layout.tsx runs PRAGMA user_version migrations before any screen reads tables - see expo-sqlite.

Related: Offline-First Basics - connectivity assumptions and UX contract

Recipe

Quick-reference stack card for field capture on SDK 57.

npx create-expo-app@latest FieldInspect --template default@sdk-57
npx expo install expo-sqlite expo-background-task expo-task-manager \
  @react-native-community/netinfo @tanstack/react-query expo-file-system expo-image

// src/sync/outboxFlush.ts (excerpt)
export async function flushOutbox(db: SQLiteDatabase) {
  const rows = await db.getAllAsync<OutboxRow>(
    `SELECT * FROM outbox ORDER BY created_at LIMIT 50`
  );
  for (const row of rows) {
    const res = await api.post("/inspections", row.payload_json, {
      headers: { "Idempotency-Key": row.idempotency_key },
    });
    if (res.ok) await markSynced(db, row.id);
  }
}

// index.ts - register background task in global scope
import "./src/background/syncTask";
import "expo-router/entry";

Device lab minimum: One rugged Android on Android 11+, one iPhone two generations behind current, both on release builds - not Expo Go.

Decisions Made

#	Decision	Choice	Rationale
1	Local source of truth	expo-sqlite with WAL	Relational inspections + outbox; not AsyncStorage blobs - expo-sqlite
2	Server snapshots	TanStack Query for job catalog	Reference lists can be stale; capture data cannot - Sync Strategies
3	Conflict policy	Server-authoritative on `approved_at`	Inspector edits after supervisor approval are discarded with audit note in UX
4	Mutation replay	Outbox + Idempotency-Key	Reconnect must not duplicate rows - Data Layer Best Practices #19–20
5	Background upload	expo-background-task supplement	Foreground flush on NetInfo is primary - Background Sync & TaskManager
6	Attachments	FileSystem paths in SQLite meta	Upload worker streams files; DB stores `local_path`, `remote_url`, `bytes_uploaded`
7	UX contract	Four visible states	Technicians trust "Pending upload" over silent failure - Offline-First Basics #2
8	Rugged testing	Physical Zebra on internal track	Scanner intents and battery saver modes do not exist on emulators - Android Basics for RN Devs
9	OTA scope	JS-only fixes on `production` channel	Schema migrations ship with store builds when `user_version` bumps

Rejected alternatives:

CRDT for checklist answers - backend had no merge engine; server-authoritative simpler for compliance.
Background sync as only path - 15-minute minimum interval missed dispatch deadline; foreground flush mandatory.
AsyncStorage outbox - 200+ pending items after multi-day outage exceeded comfortable JSON size.

Outcomes

Pilot fleet: 120 rugged devices on Android 11–14, SDK 57 build 1.6.0.

Metric	Before (online-first prototype)	After (SQLite + outbox)
Lost submissions / week	11 (user-reported)	0 in 8-week pilot
Median save latency offline	N/A (blocked spinner)	<80ms local commit
Sync within 5 min of connectivity	62%	94%
Background task success rate	-	78% (iOS stricter than Android)
Support tickets: "frozen app"	23/month	4/month

Corruption recovery: one device with a failed OTA mid-migration triggered safeParse quarantine - app rendered last-known-good inspections without white-screening per Data Layer Best Practices #13.

Lessons

SQLite migrations before first paint. A user_version bump shipped in an OTA without a store build bricked cold start once - now native schema changes require binary bump.
Show pending state per row, not global spinner. Inspectors work on job B while job A uploads; per-row synced flag beat a blocking modal.
Rugged devices lie about battery. BatterySaver on Zebra delayed background tasks; document that foreground flush is the real delivery path.
Photo uploads need byte progress. expo-file-system upload with onUploadProgress reduced "did it save?" calls to dispatch.
Logout clears all layers. Stale inspection cache on shared devices was a privacy incident class - queryClient.clear() + SQLite user tables + attachment dirs.
Pin SDK 57 in runbooks. Field IT installs APKs months later; support docs must state which runtimeVersion accepts which OTA.

Offline-First Basics - UX contract and NetInfo
expo-sqlite - WAL, migrations, transactions
Sync Strategies - server reconciliation
Optimistic UI - rollback patterns
Background Sync & TaskManager - deferred flush
expo-image - attachment thumbnails and cache
Network Failure UX - banners and retry copy
Internal Distribution - fleet APK delivery

Stack versions: This page was written for React 19.2.3, React Native 0.86.0, and Expo SDK 57 (expo ~57.0.4).

Reference: Offline-First Field App

Search Documentation

Reference: Offline-First Field App