playbooks

home / skills / harborgrid-justin / lexiflow-premium / pwa-offline-sync-manager

pwa-offline-sync-manager skill

/frontend/.github-skills/pwa-offline-sync-manager

This skill helps implement offline mutation queuing with Background Sync to replay mutations when connectivity returns, ensuring reliable offline-to-online

npx playbooks add skill harborgrid-justin/lexiflow-premium --skill pwa-offline-sync-manager

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
618 B
---
name: pwa-offline-sync-manager
description: Implement Background Sync API to queue and replay mutations when connectivity is restored.
---

# PWA Offline Sync Manager

## Summary
Implement Background Sync API to queue and replay mutations when connectivity is restored.

## Key Capabilities
- Intercept failed requests.
- Queue mutations in IndexedDB.
- Replay on connection restoral.

## PhD-Level Challenges
- Handle conflict resolution.
- Manage persistent queue order.
- Provide user feedback.

## Acceptance Criteria
- Queue a mutation offline.
- Sync automatically when online.
- Handle a conflict scenario.

Overview

This skill implements a PWA Offline Sync Manager that uses the Background Sync API to queue failed mutations and replay them when connectivity is restored. It is designed for apps that must reliably submit legal-management changes from unreliable networks. The skill focuses on queuing, ordering, replay, and conflict handling to ensure data integrity and user transparency.

How this skill works

The service worker intercepts outbound mutation requests and, when a request fails due to network loss, stores a mutation record in IndexedDB with metadata and a deterministic order key. When the Background Sync event fires or connectivity is detected, the manager replays queued mutations in order, applies optimistic UI updates or rollback on conflict, and emits events for user-facing feedback. Conflict resolution hooks let the app decide merge or manual review.

When to use it

  • Mobile or desktop web apps that must submit writes from intermittent networks
  • Legal or compliance platforms where mutation durability and ordering matter
  • Offline-first features that require deterministic replay of user actions
  • Apps that need to present clear user feedback about sync state and conflicts
  • Scenarios where background sync should reduce user burden for retrying operations

Best practices

  • Store only serializable mutation payloads and minimal metadata to keep IndexedDB small
  • Use a monotonic sequence or timestamp + UUID to maintain persistent queue order
  • Implement conflict-resolution callbacks on the client and a last-write-intent marker on the server
  • Surface concise user feedback (queued, syncing, conflict) and provide manual retry paths
  • Gracefully degrade when Background Sync is unavailable by falling back to online-detect polling

Example use cases

  • Queue contract edits from mobile users and replay edits when they return online
  • Stage signed approvals offline and transmit them in order to preserve audit trails
  • Batch update client billing metadata while preserving operation order after reconnect
  • Sync annotations made in airplane mode and resolve conflicts against server versions
  • Automatically retry form submissions that failed due to transient connectivity

FAQ

What happens if Background Sync is not supported by the browser?

The skill falls back to connectivity detection and scheduled retries from the service worker or page code; you should provide a fallback polling strategy and manual retry UI.

How are conflicts detected and resolved?

Conflicts are detected by server responses during replay; the manager exposes hooks for merge logic, automatic resolution policies, or enqueuing the mutation for user review.