[FEATURE]: Offline-First Workout Mode with Full Session Recording and Background Sync — Complete Exercise Tracking Without Internet Connection

[Nagajyothi-tammisetti]

❓ Problem Statement

Users in gyms, parks, or areas with poor connectivity cannot reliably use spectrax — the app depends on network availability for session sync and in some flows for auth token validation. When the connection drops mid-session, queued data is silently orphaned (see #939) and Firestore writes fail without recovery. Many fitness app users specifically work out in environments with unreliable connectivity, making this a major accessibility gap.

💡 Proposed Solution

Implement a complete offline-first workout mode:

• Detect network status on session start using navigator.onLine + online/offline event listeners.
• When offline, store the entire session (rep data, form scores, skeletal keypoints) to IndexedDB via a dedicated offlineSessionStore.
• Show a persistent but unobtrusive banner: "Offline mode — workout is being saved locally."
• On reconnection, automatically trigger a background sync that pushes all offline sessions to Firestore in order, with conflict resolution using the existing CRDT layer.
• Fix the silent skip bug in syncOfflineQueue ([BUG]: syncOfflineQueue silently skips ALL sessions when user is not authenticated — queued data orphaned forever #939) as part of this implementation.
• Ensure the Service Worker caches all required assets so the app shell loads without network.

🎯 Benefits

• Makes spectrax usable in gyms, outdoor parks, and travel — the most common workout environments.
• Eliminates data loss from mid-session connectivity drops, a current critical failure mode.
• Dramatically improves perceived app reliability and user trust.
• The CRDT and IndexedDB infrastructure already exists ([BUG]: CRDT persistUpdate silently loses Yjs updates on IndexedDB read/write failure — missing error handlers for IDBRequest and transaction #940) — this feature completes the offline story by adding a proper user-facing mode and fixing the sync queue bugs.
• Positions spectrax competitively against established fitness apps that all offer offline mode.

🔄 Alternatives Considered

Considered a simpler approach of just showing an error banner when offline and blocking session start. Rejected — this is a worse UX than no connectivity handling at all. The app already has IndexedDB and a CRDT layer; full offline support is achievable without a major architecture change.

🛠️ Possible Implementation

• Create src/services/offlineSessionStore.ts wrapping IndexedDB for session persistence.
• Add useNetworkStatus hook using navigator.onLine + event listeners.
• Update session.service.js to route saves through offlineSessionStore when offline, Firestore when online.
• Fix syncOfflineQueue ([BUG]: syncOfflineQueue silently skips ALL sessions when user is not authenticated — queued data orphaned forever #939) to handle unauthenticated state gracefully (queue, don't skip).
• Add OfflineBanner component (non-blocking, bottom of screen).
• Update the Service Worker to cache workout screen assets for shell-offline load.

📸 Mockups / References

No response

✅ Checklist

• I have searched existing issues before creating this feature request
• I am willing to work on this feature

📌 Additional Context

Depends on fixing #939 (syncOfflineQueue silent skip) and #943 (finalizeSession data loss) first, or as part of the same PR. Related: #940 (CRDT IndexedDB error handling). This is a large but well-scoped feature — happy to break into smaller PRs if the maintainer prefers. GSSoC-26 contribution.

[Nagajyothi-tammisetti]

Hi @Somil450,

I'd like to take this up for GSSoC-26. Could you please assign it to me? Ready to start right away.

Thanks!