← Back to glossary

Offline-First Design

Mobile Advanced

debt(d9/e9/b9/t7)

d9 Detectability Operational debt — how invisible misuse is to your safety net

Closest to 'silent in production until users hit it' (d9). Detection_hints.tools is empty and no specialist tool can detect the absence of offline-first architecture. The flaw only becomes visible when a real user loses connectivity — typically a field report or crash analytics spike, not during development or CI. There is no linter or SAST rule that flags 'this app has no sync queue.'

e9 Effort Remediation debt — work required to fix once spotted

Closest to 'architectural rework' (e9). The quick_fix describes a multi-layered solution: IndexedDB writes, optimistic UI, service worker Background Sync queuing, and server-side conflict resolution with timestamps. The common_mistakes entry explicitly states 'retrofitting it to a traditional request-response API is very difficult' and that 'the sync architecture must be designed upfront.' This is not a patch or refactor — it requires replacing the fundamental data-access and mutation model across the entire application.

b9 Burden Structural debt — long-term weight of choosing wrong

Closest to 'defines the system's shape' (b9). Offline-first is an architectural stance that affects every data read, every write, every API contract, conflict resolution strategy, and UI feedback pattern. The tags (service-worker, indexeddb, sync, pwa) and the why_it_matters text confirm it shapes how every feature is built. Every new feature must be designed to work within the sync model, making this a rewrite-or-live-with-it commitment.

t7 Trap Cognitive debt — how counter-intuitive correct behaviour is

Closest to 'serious trap — contradicts how a similar concept works elsewhere' (t7). The misconception field reveals the canonical trap: developers assume offline-first is only a reliability feature for poor-connectivity environments and therefore skip it for 'normal' apps. This directly contradicts the reality described — that zero-latency local reads benefit all users universally, including those in cities with good connectivity. The assumption that 'we have good connectivity so we don't need this' is a serious and common wrong belief that leads to architectural decisions that are very expensive to reverse.

About DEBT scoring → scored by claude-sonnet-4-6 · 2026-05-11 · reviewed by human

Also Known As

offline-first local-first offline capable offline support background sync

TL;DR

An architectural approach where applications are designed to work fully without a network connection by default, treating connectivity as an enhancement rather than a requirement.

Explanation

Offline-first inverts the traditional assumption that network availability is the default state. Instead of making network requests and showing errors when they fail, offline-first applications read from local storage first (IndexedDB, Cache API, localStorage) and synchronise with the server when connectivity is available. This requires conflict resolution strategies for data modified both locally and on the server — last-write-wins is simplest but loses data; operational transforms and CRDTs (Conflict-free Replicated Data Types) handle merging correctly. For PHP backends, offline-first typically means implementing a sync API that accepts batches of locally-generated operations with timestamps rather than a traditional REST API that expects immediate round-trips.

Common Misconception

✗ Offline-first is only for apps used in areas with poor connectivity. Offline-first benefits all users regardless of connectivity quality. Reading from local cache instead of the network makes applications feel instantaneous — zero-latency data access. Users in cities with good connectivity benefit from the speed; users in areas with unreliable connectivity benefit from reliability. The Google Docs offline mode uses offline-first principles and improves perceived performance for everyone.

Why It Matters

Mobile networks are unreliable regardless of signal strength — tunnels, elevators, event venues, and network transitions between WiFi and cellular all cause brief connectivity gaps that break applications designed with network-required assumptions. An offline-first PHP-backed application continues functioning through these gaps, queuing mutations locally and synchronising when connectivity resumes. For field service apps, forms, note-taking, and any workflow where losing work to a network hiccup is unacceptable, offline-first is the correct default architecture.

Common Mistakes

Treating offline-first as a feature to add after launch — the sync architecture must be designed upfront; retrofitting it to a traditional request-response API is very difficult.
Using localStorage for structured data — IndexedDB supports proper querying and larger storage limits; localStorage is synchronous and blocks the main thread.
Not implementing conflict resolution — silently overwriting server data with local changes when both were modified loses work.
Assuming Background Sync API is universally supported — it is Chrome-only; implement optimistic UI updates with retry queues as a universal fallback.

Code Examples

✗ Vulnerable

// Network-required — breaks completely offline
async function saveNote(note) {
    const res = await fetch('/api/notes', {
        method: 'POST',
        body: JSON.stringify(note)
    });
    if (!res.ok) throw new Error('Failed'); // user loses work
}

✓ Fixed

// Offline-first — save locally first, sync later
async function saveNote(note) {
    note.id = crypto.randomUUID();
    note.syncedAt = null;

    // Save to IndexedDB immediately
    await db.notes.put(note);
    updateUI(note); // optimistic update

    // Try to sync — queue if offline
    try {
        await fetch('/api/notes', {method:'POST', body: JSON.stringify(note)});
        await db.notes.update(note.id, {syncedAt: Date.now()});
    } catch {
        // Will retry via Background Sync when online
        await navigator.serviceWorker.ready
            .then(reg => reg.sync.register('sync-notes'));
    }
}

References

https://offlinefirst.org/