Bucket Sync

Local-first architecture that gives your browser its own bucket.

Bucket Sync transforms browser-based file management with a local storage layer using OPFS (Origin Private File System) + IndexedDB that syncs bidirectionally with S3-compatible buckets.

How It Works

1. Write locally first — All writes go to OPFS/IndexedDB instantly
2. Background sync — Changes push to S3 automatically in the background
3. Pull remote changes — New remote files download on demand or via selective sync
4. Conflict resolution — Detects and resolves bidirectional conflicts

Browser                          S3 Remote
┌─────────────┐                 ┌──────────────┐
│   OPFS      │ ──── push ────▶│  S3 Bucket   │
│   IndexedDB │ ◀─── pull ─────│              │
└─────────────┘                 └──────────────┘
     │ instant                       │ eventual
     ▼                               ▼
  User sees                     Persisted in
  immediate                     cloud storage
  response

Key Features

Offline Access

Browse and edit files without internet. Changes queue locally and sync when connectivity returns. Service Worker intercepts fetch requests for Bucket Sites offline rendering.

Content-Addressed Storage

SHA-256 hashing prevents duplicate storage. If two files have the same content, only one copy is stored locally.

Selective Sync Scope

Choose specific prefixes to sync rather than entire buckets. Useful for large buckets where you only need a subset of files locally.

Encryption at Rest

Optional AES-256-GCM encryption using the Web Crypto API. Key derivation via PBKDF2 — your encryption key never leaves the browser.

Multi-Tab Coordination

Leader election via BroadcastChannel ensures only one tab runs the sync engine at a time. No duplicate operations, no race conditions.

Conflict Resolution

When both local and remote change the same file:

Strategy	Behavior
keep-local	Local version wins
keep-remote	Remote version wins
keep-both	Creates a .conflict copy

Pinning System

Pin important files for guaranteed offline access. Pinned files are never evicted from local cache.

Eviction Management

When local storage fills up, the eviction manager clears space using configurable strategies:

• LRU — Least Recently Used
• LFU — Least Frequently Used
• Oldest — Oldest files first

Sync States

Each file tracks its sync status:

State	Meaning
synced	Local hash matches remote ETag
dirty	Local changes not yet pushed
stale	Remote has a newer version
conflict	Both sides changed
pending-delete	Deleted locally, not yet on S3
orphan	Exists locally, deleted remotely

Event System

Subscribe to real-time sync events:

syncEngine.on('sync:start', () => console.log('Sync started'));
syncEngine.on('sync:complete', (stats) => console.log('Synced', stats));
syncEngine.on('conflict', (file) => console.log('Conflict:', file));
syncEngine.on('error', (err) => console.error('Sync error:', err));

Architecture

The sync engine is implemented in 9 phases:

1. Local Bucket — OPFS + IndexedDB storage layer
2. Sync Engine — Bidirectional S3 sync
3. Manifest & Metadata — Content-addressed file tracking
4. Selective Sync — Prefix-based sync scopes
5. Conflict Resolution — Merge strategies
6. Encryption — AES-256-GCM at rest
7. Eviction — Cache management
8. Multi-Tab — Leader election
9. Service Worker — Offline fetch interception