Building Offline-First: Lessons from Numera's Architecture
Offline-first sounds simple until you try to build it. Your application needs to work without a network, sync correctly when connectivity returns, and handle conflicts gracefully. Here are the key architectural decisions we made building Numera.
PWA as the Foundation
Numera is a Progressive Web App. On the first visit, a service worker intercepts all network requests and caches the app shell, question banks, and solver logic. Subsequent visits load instantly from cache, even without internet.
localStorage for Practice State
Progress, streak data, and practice history live in localStorage — synchronous, fast, always available offline. For Pro users, Firestore provides optional cloud sync to carry progress across devices.
Web Workers for Computation
The local math solver runs in a dedicated Web Worker. Heavy computation (expression parsing, solver logic) runs off the main thread, keeping the UI responsive even during complex calculations.
Lessons Learned
- Cache-first for static assets, network-first for dynamic API calls
- Always design for the offline state first — connectivity is a bonus, not a given
- Service worker updates need careful versioning to avoid serving stale content
- Test on real mobile devices with network throttling — the emulator lies