Offline-First Sync Protocol Skill

Offline-First Sync Protocol

Core Responsibilities

1. Encrypted Local Storage

User-Controlled Encryption

All data encrypted with user-controlled keys
SQLite database with encryption at rest
Keys never stored in plain text
User can export encrypted backups

Key Features:

Fernet encryption for secure storage
Automatic timestamp tracking
Efficient query performance
Export/import capabilities

Reference: encryption.md for complete implementation

2. Conflict Resolution

Intelligent Conflict Resolution

Multiple resolution strategies (timestamp, priority, merge)
Automatic conflict type detection
User choice for critical conflicts
Merge-compatible data structures

Resolution Strategies:

Timestamp: Most recent change wins
Priority: Higher priority data wins
Merge: Recursively merge compatible structures
User Choice: Explicit user decision

Reference: conflict-resolution.md for strategies and algorithms

3. Incremental Sync

Delta-Based Synchronization

Only sync changed data (delta sync)
Tracks sync state across sessions
Handles batch operations efficiently
Automatic retry on failure

Sync Components:

Local change detection
Remote change application
State persistence
Conflict handling

Reference: incremental-sync.md for sync logic and state management

4. Privacy-First Architecture

Zero-Knowledge Sync

Explicit user permission for all data sharing
Anonymization of sensitive fields
End-to-end encryption
Purpose-limited data usage

Privacy Principles:

Data minimization
Explicit consent
Encryption everywhere
Zero-knowledge design

Reference: privacy-first.md for anonymization and permission models

Implementation Patterns

Pattern 1: Offline-First App Storage

# Initialize encrypted storage
store = EncryptedLocalStore(
    db_path="./app_data.db",
    user_key=user_provided_key
)

# Store data (automatically encrypted)
store.store("user_preferences", {
    "theme": "dark",
    "language": "en",
    "model_preferences": {"quality": "high"}
})

# Data encrypted with user's key, never leaves device unencrypted

Pattern 2: Conflict-Aware Sync

# Configure incremental sync
sync_manager = IncrementalSync(local_store=store)

# Prepare and send sync package
sync_package = sync_manager.prepare_sync_package()
server_response = sync_to_server(sync_package)

# Apply remote changes with automatic conflict resolution
applied, conflicts = sync_manager.apply_remote_changes(
    server_response['changes']
)

# Conflicts automatically resolved, user notified if needed

Pattern 3: Privacy-Preserving Sync

# Request explicit permission
if privacy_sync.request_sync_permission(
    data_type="model_usage_stats",
    purpose="improve_model_quality"
):
    # Sync only anonymized data
    privacy_sync.sync_with_privacy(
        data=usage_stats,
        destination="model_improvement_server"
    )

Sync States

The system operates through clear state transitions:

Offline: All changes stored locally
Syncing: In progress with remote server
Conflict: Conflicts detected, awaiting resolution
Up-to-Date: Synchronized successfully
Error: Sync failed, will retry

State Management: sync-states.md for state machine and transitions

Quality Gates

✓ All data encrypted with user-controlled keys ✓ No raw sensitive data transmitted ✓ Conflicts detected and resolved within 24 hours ✓ Sync completes within 30 seconds on stable connection ✓ Offline mode fully functional for 30+ days ✓ User can export/import their encrypted data ✓ Explicit permission for all data sharing ✓ Privacy-preserving sync patterns enforced

Files Generated

encrypted_storage.py: User-key encrypted local database
conflict_resolution.py: Intelligent conflict resolution strategies
incremental_sync.py: Delta-based synchronization logic
privacy_sync.py: Privacy-preserving sync patterns
sync_state_manager.py: Sync state tracking and management

Next Steps

Initialize EncryptedLocalStore with user key
Configure conflict resolution strategy
Set up incremental sync with state tracking
Implement privacy-first permission system
Test sync across network disruptions
Verify encryption and privacy guarantees
Add sync state monitoring to UI

Agent Skills: Offline-First Sync Protocol

Install this agent skill to your local

Skill Files