ADR-0011: Offline Caching and Sync Strategy

Status: Accepted Date: 2026-02-16 Authors: OSHUN Platform Engineering, OSHUN Mobile Engineering, OSHUN Web Engineering Reviewers: Domain Leads (Tara, Veritas, Nyx, Arete) Supersedes: N/A Superseded by: N/A

Context and Problem Statement#

OSHUN must remain useful under intermittent or absent network conditions across:

• mobile (iOS/Android)
• website/PWA

Repository evidence shows strong but fragmented offline approaches:

• Tara web SW uses cache-first for static/audio and network-first for navigation.
• Veritas web includes service worker caching plus background sync queue patterns.
• Nyx PWA uses Workbox runtime caching (NetworkFirst API, CacheFirst assets/fonts/images) and local data persistence.
• Veritas mobile has offline article cache + sync queue + eviction logic.
• Tara mobile includes queue-driven download manager and storage controls.

We need one OSHUN policy for what to cache, how to sync writes, and how to handle failures safely.

Decision Drivers#

• Reliability for core shell journeys during connectivity loss.
• Consistency across mobile and web/PWA behavior.
• Safety for write operations and conflict handling.
• Performance through predictable caching and prefetch policies.
• Storage discipline on constrained mobile devices.
• Observability for offline failure and recovery behavior.

Considered Options#

Option 1: Network-Only Dynamic Data, Minimal Offline#

Description: cache static assets only; all dynamic content requires network.

Pros:

• ✅ Lowest complexity
• ✅ Minimal cache invalidation risk

Cons:

• ❌ Poor user experience in weak connectivity
• ❌ Shell feels fragile in daily mobile contexts
• ❌ Misses key OSHUN reliability goals

Option 2: Cache-First for Most Data#

Description: aggressive cache-first for static and dynamic data.

Pros:

• ✅ Very fast perceived loads
• ✅ More content available offline

Cons:

• ❌ High staleness risk for time-sensitive data
• ❌ Complex invalidation and consistency issues
• ❌ Risky for personalized/entitled content

Option 3: Hybrid Policy - Cache-First Static, Network-First Dynamic (Chosen)#

Description: static assets use cache-first; dynamic personalized/API data uses network-first with stale fallback; write operations queue offline and sync later.

Pros:

• ✅ Strong balance of freshness and resilience
• ✅ Aligns with proven patterns already in repo
• ✅ Better control over stale-data risk
• ✅ Clear policy matrix for implementation and QA

Cons:

• ❌ Requires robust sync queue/conflict handling
• ❌ More moving parts than minimal offline strategy

Decision Outcome#

Chosen option: Option 3 - hybrid offline strategy.

Normative Cache Policy Matrix#

Offline Write Queue Rules (Mandatory)#

• Queue all non-destructive writes when offline.
• Each queued op includes:
  • stable operation id
  • operation type
  • payload
  • creation time
  • retry count
• Replay on reconnect with exponential backoff + jitter.
• Stop retry after max attempts and surface recoverable UI state.
• Queue processor must be idempotent-safe to prevent duplicate side effects.

Conflict Resolution Rules#

• Default strategy: server-authoritative merge for shared resources.
• Local optimistic state must rollback on authoritative rejection.
• For preference toggles, last-write-wins with server timestamp.
• For list toggles (save/unsave), de-duplicate by operation id and latest intent.

Storage and Eviction Rules#

• Define per-platform cache budgets and hard ceilings.
• Evict using policy by class:
  • media: LRU with bookmark/pin protections where applicable
  • feed/API cache: TTL-based purge + LRU fallback
• Display user-visible storage usage and allow manual cleanup actions.

Prefetch Rules#

• Prefetch only on adequate connection (prefer Wi-Fi, respect data saver).
• Prioritize:
  • continue/resume items
  • recently used domain surfaces
  • user-saved critical content
• Abort/limit prefetch when offline, low battery, or constrained network.

UX and Product Rules#

• Always show global online/offline state indicator in shell.
• For stale fallback content, show freshness timestamp.
• Provide explicit retry actions on failed fetch/sync.
• Never silently drop user write actions.

Platform Implementation Guidance#

Mobile#

• Use managed local stores (AsyncStorage/SQLite/file system) by data class.
• Use queued sync for write actions and media download manager for offline media.
• Persist sync queue across app restarts.

Web/PWA#

• Use service worker strategies per matrix.
• Use IndexedDB for offline data models and sync queues.
• Use Background Sync where supported; fallback to foreground replay.

Existing Pattern Alignment#

• Aligns with Tara web SW strategy for static/nav split.
• Aligns with Veritas web sync-manager queue model.
• Aligns with Nyx Workbox runtime caching patterns.
• Aligns with Veritas mobile offline cache + queue + eviction pattern.

Implementation Plan#

Phase 1: Policy and Contracts#

• Define libs/oshun/offline policy APIs and cache classes.
• Define queue item schema and sync result taxonomy.
• Define per-endpoint cache classification.

Phase 2: Shell Integration#

• Integrate global offline status and retry UX in shell.
• Integrate queue persistence and replay orchestration.
• Integrate stale-data indicators for fallback reads.

Phase 3: Hardening#

• Add cache budget enforcement and eviction diagnostics.
• Add conflict resolution integration tests.
• Add partial-outage and airplane-mode scenario tests.

Phase 4: Observability#

• Emit offline/sync events for dashboarding.
• Add alerts for queue growth, replay failures, and stale fallback spikes.

Success Metrics#

• Core shell routes render with meaningful fallback in offline mode.
• Queue replay success rate >= 98% after reconnection.
• No silent write loss for queued operations.
• Cache growth remains within configured budgets across target devices.
• Offline-to-online recovery latency meets UX SLA.

Consequences#

Positive Consequences#

• ✅ Stronger reliability for real-world network conditions.
• ✅ Consistent offline behavior across mobile and web/PWA.
• ✅ Explicit and testable policy for caching and sync.
• ✅ Better trust via visible state/retry/fallback behavior.

Negative Consequences#

• ❌ Higher implementation complexity (queue + conflict logic).
• ❌ More QA permutations (network/state/storage combinations).
• ❌ Ongoing tuning needed for cache and prefetch budgets.

Risks and Mitigations#

Security and Compliance#

• Do not cache sensitive auth/session responses.
• Encrypt or protect sensitive local data where required by policy.
• Respect user consent/privacy settings in offline telemetry collection.

Monitoring and Observability#

Track:

• offline entry/exit events
• cache hit/miss rates by data class
• queue depth and replay outcomes
• conflict resolution outcomes
• fallback-render counts and stale age distributions

Related Decisions#

• docs/adr/ADR-0014-oshun-web-and-pwa-strategy.md
• docs/adr/ADR-0016-shared-identity-and-cross-domain-session-model.md

References#

• apps/tara/web/public/sw.js
• apps/veritas/web/public/sw.js
• apps/veritas/web/src/lib/offline/sync-manager.ts
• apps/nyx/mobile/vite.config.ts
• apps/veritas/mobile/src/services/offline.ts
• apps/tara/mobile/src/services/download.ts