Local-First

Local-first software stores data primarily on the user's device, with the cloud serving as an optional sync layer. Unlike cloud-first applications where data lives on servers, local-first apps work completely offline and treat the network as a convenience, not a requirement.

Core Principles

1. Data lives locally: The user's device is the source of truth
2. Works offline: Full functionality without internet
3. Sync is optional: Cloud enhances, but isn't required
4. User owns data: Data accessible without the service
5. Fast by default: No network latency for local operations

Local-First vs Offline-First

Aspect	Local-First	Offline-First
Data location	Device is primary	Cloud is primary
Offline capability	Complete	Graceful degradation
Sync model	Eventual, background	Eager, on reconnect
Data ownership	User controls	Service controls

Architecture

┌─────────────────────────────────────────┐
│  Local Device                           │
│  ┌─────────────────────────────────┐   │
│  │  Application                     │   │
│  │  ┌───────────┐  ┌───────────┐   │   │
│  │  │ UI Layer  │  │ Business  │   │   │
│  │  └───────────┘  │ Logic     │   │   │
│  │                 └───────────┘   │   │
│  │  ┌─────────────────────────┐   │   │
│  │  │ Local Database          │   │   │
│  │  │ (IndexedDB, SQLite)     │   │   │
│  │  └─────────────────────────┘   │   │
│  └─────────────────────────────────┘   │
│                  ↕ Sync (optional)      │
└─────────────────────────────────────────┘
                   ↕
           ┌───────────────┐
           │  Cloud Sync   │ (optional)
           └───────────────┘

Key Technologies

Technology	Purpose
IndexedDB	Browser storage
CRDTs	Conflict-free sync
Automerge	CRDT library
Yjs	Real-time collaboration
RxDB	Local database with sync for web & mobile

Conflict Resolution

When multiple devices edit the same data:

// CRDT-based merge (automatic)
// Device A: "Hello " → "Hello World"
// Device B: "Hello " → "Hello Earth"
// Result: "Hello WorldEarth" (interleaved characters)

// Last-write-wins (simple but lossy)
// Result: Most recent change wins

// Custom merge (application-specific)
// Result: Prompt user or apply domain logic

What We Like

• Instant response: No network round-trips
• Privacy: Data doesn't leave the device
• Reliability: Works regardless of connectivity
• Ownership: Users can export and control their data
• Longevity: Works even if service shuts down

What We Don't Like

• Complexity: Sync and conflict resolution are hard
• Storage limits: Device storage is finite, but can be quite large if you use IndexedDB (unlike localStorage)
• Multi-device: Need sync infrastructure for multiple devices
• Collaboration: Real-time collaboration adds complexity

Use Cases

• Privacy-focused applications
• Mobile apps in low-connectivity areas
• Scientific data collection in the field
• Use cases requiring longevity (data survives app, device, or service changes)
• Apps that need instant speed/response without cloud latency

Related Concepts

• Offline-first: Works offline but cloud-centric
• PWA: Web apps with offline capabilities
• IndexedDB: Browser-based storage