wip

TASK_CACHING.md

@@ -0,0 +1,142 @@
+# 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)
+```kotlin
+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**: `mycrib_cache`
+- **Key**: `cached_tasks`
+- **Format**: JSON string
+
+### iOS
+- **Location**: NSUserDefaults
+- **Key**: `cached_tasks`
+- **Format**: JSON string
+
+### JVM/Desktop
+- **Location**: Java Preferences
+- **Node**: `com.mycrib.cache`
+- **Key**: `cached_tasks`
+- **Format**: JSON string
+
+## Usage
+
+### Accessing Cached Tasks
+
+**Kotlin/Android:**
+```kotlin
+val tasks by LookupsRepository.allTasks.collectAsState()
+// Tasks are available immediately from cache, updated when API responds
+```
+
+**Swift/iOS:**
+```swift
+@ObservedObject var lookupsManager = LookupsManager.shared
+// Access via: lookupsManager.allTasks
+```
+
+### Manual Operations
+
+```kotlin
+// 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.)