Feature: Cross-Device Session Sync and Offline Action Queue

Summary

Add cross-device session continuity and an offline action queue so Moodify users can start a mood/recommendation flow on one client, continue it on another, and avoid losing history or feedback actions during temporary network failures.

Problem / Opportunity

Moodify has both web and React Native clients. Each client can analyze moods, fetch recommendations, save history, and open Deezer links, but session state is mostly local to the current client. Mobile already has some graceful fallback behavior, yet actions like saving mood history, recommendations, listening events, and future feedback can still be lost if the network drops or if the user switches devices mid-flow.

A durable sync layer would make the multi-platform product feel cohesive and would improve data quality for personalization without overlapping the existing inference stability issue, which focuses on low-memory/CPU service resilience.

Proposed Feature

Create a lightweight sync model for user activity and current recommendation sessions:

• Define a session/activity record for mood analysis results, recommendation sets, selected filters, and timestamps.
• Persist recent sessions for authenticated users so web and mobile can resume the latest flow.
• Add an offline queue on mobile and web for mood saves, recommendation saves, listening events, and feedback events.
• Retry queued actions with idempotency keys to prevent duplicate history entries.
• Surface sync status in settings/profile where users can see pending actions and retry or discard them.
• Keep anonymous users local-only while preserving a path to merge local queued actions after login.

Scope

• Backend API for recent sessions and idempotent activity ingestion.
• Client-side queue storage for web and mobile.
• Sync/resume UI in Results/Profile/Settings surfaces.
• Duplicate prevention for listening and recommendation saves.
• Tests for idempotency, queue retry behavior, and session resume contracts.

Acceptance Criteria

• Authenticated users can resume their most recent recommendation session across web and mobile.
• Mood saves, recommendation saves, listening events, and feedback-ready events can be queued locally when the API is unavailable.
• Queued actions retry automatically when connectivity returns or when the app is reopened.
• Idempotency keys prevent duplicate history entries when retrying the same queued action.
• Users can view pending queued actions and manually retry or discard them.
• Anonymous sessions remain local and do not upload until the user signs in and confirms merge behavior.
• Tests cover idempotent ingestion, queue persistence, retry success, retry failure, and cross-device session retrieval.

Non-Goals

• Real-time collaborative listening.
• Push notifications.
• Full background sync guarantees on every mobile OS version.
• Replacing the current JWT authentication flow.

Dependencies / Risks

• Requires a canonical event schema shared by web, mobile, and backend.
• Offline storage must avoid saving sensitive payloads longer than necessary.
• Session resume should not surprise users by replaying stale recommendations as if they were freshly generated.

Open Questions

• How long should recent recommendation sessions be retained?
• Should local anonymous activity merge automatically after login or require explicit confirmation?
• Which client storage mechanism should be used on web for queued actions: localStorage, IndexedDB, or a small wrapper that can evolve later?