Offline-First Client Synchronization Engine Spec

Role: Lead Client-Side Distributed Systems Engineer specializing in progressive web applications.

Context

• Client Storage Engine: {{client_database}}
• Server Transport Protocol: {{backend_api_protocol}}
• Conflict Resolution Strategy: {{conflict_resolution_strategy}}
• Max Offline Retention: {{max_offline_retention_days}} days
• Connectivity Polling Frequency: {{network_heartbeat_interval_ms}} ms
• Authentication Lifecycle: {{auth_token_refresh_flow}}

Task

Produce a technical synchronization engine specification for an offline-first web client, defining local schema design, mutation queue processing, retry backoff schemes, and deterministic conflict reconciliation against {{backend_api_protocol}}.

Method

1. Design the local storage schema and mutation ledger inside {{client_database}}, tracking operation idempotency keys, timestamps, and entity states.
2. Specify the network state detector and heartbeat polling mechanism using {{network_heartbeat_interval_ms}} intervals.
3. Formulate the queue worker state machine detailing transition states: IDLE, DRAINING, PAUSED, RETRYING, and FAILED.
4. Detail the handling of {{auth_token_refresh_flow}} when processing queued requests after token expiration while offline.
5. Define the exact merge rules dictated by {{conflict_resolution_strategy}} (e.g., Last-Write-Wins, CRDT, or 3-Way Merge).
6. Establish data pruning and eviction rules once locally cached mutation history exceeds {{max_offline_retention_days}} days.
7. Construct telemetry tracking for sync latency, conflict rates, and failed mutation recovery.

Constraints

• MUST include concrete JSON schemas for the local mutation queue item and sync payload.
• MUST NOT allow offline data writes to block the UI main thread.
• MUST specify exponential backoff parameters with jitter for network reconnect retries.
• Keep the specification concrete, focusing on deterministic edge cases over general theory.

Output format

• 1. Storage & Schema Specification (with JSON schema structures)
• 2. Synchronization Queue State Machine
• 3. Conflict Resolution Protocol & Edge Case Matrix
• 4. Security & Offline Session Handling
• 5. Telemetry, Recovery & Purge Policies

Self-review

• Does the conflict resolution section explicitly define client vs server tie-breaking behavior?
• Are all offline retention and queue expiration limits accounted for?
• Is the authentication renewal flow secure against stale token replay during sync?