Achieving Offline-First Durability for Web Applications with IndexedDB
This article explores architectural patterns for building robust offline-first Progressive Web Applications (PWAs), focusing on client-side data durability. It demonstrates how to persist both application state (user documents) and in-flight operations (AI jobs) using IndexedDB, ensuring user work is never lost due to browser refreshes or network interruptions. The core principle involves writing job intent to local storage *before* network requests to guarantee recovery.
Read original on Dev.to #architectureBuilding offline-first web applications requires more than just caching static assets; it demands a robust strategy for client-side data durability. The article highlights the challenge of maintaining application state and long-running operations in the browser, which is inherently volatile. Modern web applications, especially those with complex editors or background processes like AI generation, must gracefully handle scenarios such as accidental tab closures, network loss, or page refreshes without losing user progress.
The Durability Challenge: Document State and In-Flight Jobs
The primary focus for offline-first durability revolves around two critical aspects:
- Working Document State: Ensuring the user's canvas or editor content is restored exactly as they left it after any interruption.
- In-Flight Operations: Guaranteeing that long-running tasks, such as AI generation jobs, either complete or can be resumed, preventing silent failures and lost charges.
IndexedDB as the "Kitchen Ticket Rail"
The article proposes IndexedDB as the ideal solution for client-side persistence, drawing an analogy to a kitchen ticket rail. Just as a ticket on a rail ensures an order isn't lost if the chef walks away, IndexedDB provides a durable record of both the working document and pending jobs. This approach moves critical state out of ephemeral memory into a persistent, structured storage mechanism available in the browser.
Why IndexedDB over localStorage?
IndexedDB is preferred because it's asynchronous (non-blocking), offers large storage capacity, and can store structured data and binary blobs. In contrast, localStorage is synchronous, small, and string-only, making it unsuitable for complex application states or large documents.
Atomic Operations for Job Durability
A key architectural decision for handling in-flight operations is to record the job intent in IndexedDB *before* making the network request. This ensures that even if the browser crashes immediately after the user initiates an action but before the network request completes, the job's existence and status are preserved. Upon reload, the application can query IndexedDB, identify `queued` or `running` jobs, and resume or retry them, significantly improving reliability.
// 1. record intent BEFORE the request
const job = { id: uuid(), prompt, status: 'queued', createdAt: Date.now() }
await db.put('jobs', job)
// 2. submit, then persist the remote handle
const { remoteId } = await api.submit(prompt)
await db.put('jobs', { ...job, status: 'running', remoteId })This pattern creates a resilient front-end architecture where the UI can be rebuilt from persisted data, ensuring a seamless user experience even in unreliable network conditions or volatile browser environments. Decoupling job status from UI rendering through an observer pattern further enhances maintainability and robustness.