honeyDueKMP/TASK_CACHING.md

Task Disk Caching

Overview

All user tasks are automatically cached to disk for offline access. This provides a seamless experience even when the network is unavailable.

How It Works

On App Startup (After Login)

LookupsRepository.initialize()

1. Loads cached tasks from disk immediately - Instant access to previously fetched tasks
2. Fetches fresh data from API - Updates with latest data when online
3. Saves to disk - Overwrites cache with fresh data

Cache Flow

App Start
    ↓
Load from Disk Cache (Instant offline access)
    ↓
Fetch from API (When online)
    ↓
Update Memory + Disk Cache
    ↓
UI Updates Automatically

Platform Storage

Android

• Location: SharedPreferences
• File: honeydue_cache
• Key: cached_tasks
• Format: JSON string

iOS

• Location: NSUserDefaults
• Key: cached_tasks
• Format: JSON string

JVM/Desktop

• Location: Java Preferences
• Node: com.honeydue.cache
• Key: cached_tasks
• Format: JSON string

Usage

Accessing Cached Tasks

Kotlin/Android:

val tasks by LookupsRepository.allTasks.collectAsState()
// Tasks are available immediately from cache, updated when API responds

Swift/iOS:

@ObservedObject var lookupsManager = LookupsManager.shared
// Access via: lookupsManager.allTasks

Manual Operations

// Refresh from API and update cache
LookupsRepository.refresh()

// Clear cache (called automatically on logout)
LookupsRepository.clear()

Benefits

✅ Offline Access - Tasks available without network ✅ Fast Startup - Instant task display from disk cache ✅ Automatic Sync - Fresh data fetched and cached when online ✅ Seamless UX - Users don't notice when offline ✅ Battery Friendly - Reduces unnecessary API calls

Cache Lifecycle

On Login

• Loads tasks from disk (if available)
• Fetches from API
• Updates disk cache

During Session

• Tasks served from memory (StateFlow)
• Can manually refresh with LookupsRepository.refresh()

On Logout

• Memory cache cleared
• Disk cache cleared (for security)

On App Restart

• Cycle repeats with cached data from disk

Implementation Files

Common:

• TaskCacheStorage.kt - Unified cache interface
• TaskCacheManager.kt - Platform-specific interface

Platform Implementations:

• TaskCacheManager.android.kt - SharedPreferences
• TaskCacheManager.ios.kt - NSUserDefaults
• TaskCacheManager.jvm.kt - Java Preferences

Repository:

• LookupsRepository.kt - Cache orchestration

Storage Size

Tasks are stored as JSON. Approximate sizes:

• 100 tasks ≈ 50-100 KB
• 1000 tasks ≈ 500 KB - 1 MB

Storage is minimal and well within platform limits.

Error Handling

If cache read fails:

• Logs error to console
• Returns null
• Falls back to API fetch

If cache write fails:

• Logs error to console
• Continues normally
• Retry on next API fetch

Security Notes

• Cache is cleared on logout
• Uses platform-standard secure storage
• No sensitive authentication data cached
• Only task data (titles, descriptions, status, etc.)