Offline-First Calisthenics App Architecture

When training at a calisthenics park, gym basement, or outdoor field, internet connectivity is notoriously unreliable. Requiring an active cloud network request just to log a set of push-ups or check a skill tree creates unnecessary friction.

In building Flowzy, we made an architectural commitment: The client browser is the source of truth.

---

1. High-Level System Architecture

Flowzy utilizes a three-tier local storage architecture:

• Layer 1: React Component State (Instant UI re-render)
• Layer 2: Browser Local Storage / IndexedDB (Persistent 0ms client write)
• Layer 3: Background Network Sync (Idempotent cloud reconciliation)

---

2. Service Worker & App Shell Caching

Using Workbox with Next.js App Router, the application pre-caches the complete App Shell (HTML, CSS, JS bundles, icons, and core fonts) during initial load.

Exercise videos are cached on-demand using a CacheFirst strategy with a 30-day expiration window.

---

3. Synthesizing Zero-Latency Tones via Web Audio API

Instead of loading external MP3 audio files for workout countdown timers and rep cues (which can fail to buffer offline), Flowzy synthesizes audio frequencies natively using the Web Audio API.

When a timer triggers, an AudioContext oscillator is created dynamically, generating a clean 880Hz sine wave tone directly through the device speaker with zero network dependency.

---

4. Key Performance Metric Comparisons

---

5. Lessons Learned & Best Practices

• Idempotent Mutations: Design local state updates so they can be replayed safely during background network reconciliation.
• Optimistic UI: Never block the user interface with loading spinners for simple input actions. Render the updated state immediately.
• Graceful Fallbacks: If Web Audio or Haptics APIs are unsupported on older browser engines, swallow errors silently without breaking execution.