Offline-First Architecture: Sync, Conflicts, Authentication and Security

Offline-first architecture treats the local database as the immediate source of truth for the user interface and synchronizes changes with the server in the background. It does not simply cache a few screens. It defines how records are identified, queued, retried, merged, secured and reconciled across devices.

This architecture is valuable for point-of-sale systems, field applications, logistics, healthcare and any product used with unreliable connectivity. The hard part is not saving data locally. The hard part is making two valid histories agree after they diverge.

Offline-first vs offline-capable

Approach	Behavior	User experience
Online-only	Reads and writes require the server	Stops when the network fails
Offline-capable	Caches selected data and may queue limited actions	Some screens work offline
Offline-first	Core reads and writes happen locally, then synchronize	Primary workflows remain responsive without a connection

Offline-first is not necessary for every product. It adds schema, security, testing and support complexity. Use it when offline work is a product requirement, not as a fashionable architecture.

Core architecture

1. Local database: stores the records required by the device.
2. Repository layer: gives the interface one consistent API for local reads and writes.
3. Outbox: records unsynchronized local mutations.
4. Sync engine: pushes outbox operations and pulls remote changes.
5. Conflict resolver: applies explicit rules when histories overlap.
6. Server change log: exposes records changed after a cursor or version.
7. Observability: records failures, retries, conflicts and sync progress.

The user interface should read from the local database even while online. Network responses update local state, which then updates the interface. This avoids maintaining separate online and offline code paths.

Use stable client-generated IDs

A device must identify a new record before the server sees it. Use a globally unique client-generated identifier such as UUIDv7 or ULID. Do not assign temporary negative integer IDs and later replace them, because related records, retries and logs can retain the temporary value.

The server should accept the client ID, verify that it belongs to the authenticated tenant and make repeated creation requests idempotent.

The outbox pattern

When a user changes data, commit the business record and an outbox operation in the same local database transaction. The interface succeeds immediately after that transaction. A background worker sends pending outbox operations when a connection is available.

// Local outbox operation
{
  "operation_id": "019...",
  "entity_type": "sale",
  "entity_id": "019...",
  "action": "create",
  "base_version": 0,
  "payload": { "total": 125000, "currency": "UGX" },
  "created_at": "2026-08-10T18:30:00Z",
  "attempts": 0
}

Keep the operation ID stable across retries. The server stores processed operation IDs and returns the original outcome if the device sends the same operation again.

Idempotency prevents duplicate actions

Networks fail at ambiguous moments. A client can send a sale, lose the response and retry even though the server committed it. Without idempotency, one button press becomes two sales.

Send an idempotency key for every business mutation. On the server:

1. Authenticate and authorize the request.
2. Look up the key within the tenant and endpoint scope.
3. Return the stored response if it already exists.
4. Otherwise, execute the mutation and store the key and response atomically.
5. Reject reuse with a different payload.

Payment providers use the same principle because a timeout cannot reveal whether a transaction completed.

Pull changes with a cursor

A device needs records changed since its last successful pull. A simple timestamp can miss changes when clocks differ or several rows share the same precision. Prefer a server-issued monotonic cursor backed by a change sequence.

GET /api/sync/changes?cursor=184205&limit=500

The response should include changed records, tombstones for deletions and the next cursor. Advance the local cursor only after applying the complete page in a transaction.

Do not synchronize every server table

Sync a device-specific projection, not a database dump. A cashier device may need products, prices, assigned branch stock, customers and its recent sales. It probably does not need payroll, all audit logs or other tenants’ records.

Server authorization must filter every pull. Hiding data in the interface is not access control.

Conflict detection

A conflict occurs when the device edits a record based on version 4 while the server has already moved to version 5. Include the base version in every update. The server compares it with the current version before committing.

Strategy	Use when	Risk
Last write wins	Low-value preferences	Silently loses valid changes
Field-level merge	Different fields changed independently	Business rules can still conflict
Additive operations	Counters, stock movements and ledgers	Requires immutable event design
Manual resolution	Both versions have business value	Creates operational work
Server authority	Permissions, pricing or compliance rules	Local edit may be rejected

Do not use one global rule. Product descriptions, stock, payments and user permissions require different conflict policies.

Model inventory as movements, not overwrites

Two devices that both set stock to 9 can destroy information. Instead, record immutable movements such as sale minus two, return plus one and adjustment minus three. The current balance is the sum of authorized movements.

Each movement needs a unique ID, product, branch, quantity delta, reason, source operation and time. The server remains responsible for constraints such as whether negative stock is permitted.

Deletion needs tombstones

If the server physically removes a row, an offline device cannot learn that the record disappeared. Keep a tombstone with the entity ID, deletion version and deletion time long enough for active devices to synchronize.

Expired devices may need a full re-bootstrap when their cursor is older than the tombstone retention window.

Offline authentication and authorization

Offline authentication proves that a previously authorized user can unlock the local application. It cannot confirm that the server has not disabled that user since the last sync.

• Require a successful online login before enabling offline access.
• Store tokens and local encryption keys in platform secure storage.
• Use a local PIN only to unlock protected credentials, not as the server password.
• Apply an offline authorization expiry appropriate to the risk.
• Cache the minimum role and branch scope.
• Revalidate permissions when connectivity returns.
• Block high-risk actions offline when current authorization is essential.

Never store plaintext passwords. A device marked as revoked should wipe or lock protected business data after it receives that state.

Security requirements

• Encrypt sensitive local data and protect keys with the operating system keystore.
• Use TLS for every synchronization request.
• Authorize each operation on the server. Do not trust a device role claim by itself.
• Validate payloads and enforce tenant boundaries.
• Sign or authenticate device sessions and support remote revocation.
• Avoid logging secrets, full tokens or unnecessary personal data.
• Rate-limit sync endpoints and cap batch sizes.
• Record an audit trail for important offline actions.
• Verify application updates to reduce tampered-client risk.

Flutter local data flow

// Write the record and outbox item atomically.
await database.transaction(() async {
  await salesRepository.insertLocal(sale);
  await outboxRepository.enqueue(
    SyncOperation.create(entity: sale),
  );
});

// The UI observes local state. Sync runs independently.
syncScheduler.requestRun();

Keep transport models separate from local entities. The server can evolve without forcing every table in the device database to mirror an API response exactly.

Laravel synchronization endpoint

Use a dedicated service to validate, authorize and process operations. Wrap each idempotent mutation in a database transaction. Return a machine-readable result for every operation in a batch.

public function push(PushSyncRequest $request): JsonResponse
{
    $results = $this->syncService->processBatch(
        user: $request->user(),
        deviceId: $request->validated('device_id'),
        operations: $request->validated('operations'),
    );

    return response()->json(['results' => $results]);
}

Run Laravel commands through Sail when the project uses Docker, for example:

./vendor/bin/sail artisan make:controller Api/SyncController
./vendor/bin/sail artisan make:request PushSyncRequest
./vendor/bin/sail artisan test --filter=Sync

Retry strategy

• Retry temporary network and server failures with exponential backoff and jitter.
• Do not automatically retry validation or authorization failures.
• Stop retrying an operation after a defined limit and show a resolvable error.
• Preserve ordering only where the business rule requires it.
• Do not let one poisoned operation block unrelated records forever.

Testing an offline-first application

• Lose the connection before sending, during upload and after the server commits.
• Send the same operation repeatedly.
• Edit the same record on two devices.
• Move the device clock forward and backward.
• Revoke the user while the device is offline.
• Run out of storage during a local transaction.
• Pull several pages and fail before the final page.
• Delete and recreate related records.
• Upgrade the local database with pending outbox operations.
• Attempt to synchronize data from another tenant.

Use property-based and randomized tests for ordering, retries and duplicate delivery. Happy-path unit tests are not enough for distributed state.

Common mistakes

• Using connectivity status as proof that a request will succeed.
• Sending full database tables on every sync.
• Trusting device timestamps for ordering.
• Applying last-write-wins to money or stock.
• Retrying non-idempotent operations.
• Deleting server rows without tombstones.
• Storing passwords for offline login.
• Building a second UI path for offline mode.
• Hiding unresolved sync failures from the user.

The bottom line

Offline-first architecture is a controlled distributed system. Stable IDs, an atomic outbox, idempotent APIs, cursor-based pulls and domain-specific conflict rules make it dependable. Add secure local storage, server-side authorization and failure testing before calling it production-ready. When those foundations are correct, unreliable connectivity becomes a background condition instead of a broken user experience.