POWR/docs/design/cache-management.md

# NDK Mobile Cache Integration Plan

This document outlines our plan to leverage the NDK mobile SQLite cache system throughout the POWR app to improve offline functionality, reduce network usage, and enhance performance.

## Overview

The NDK mobile library provides a robust SQLite-based caching system that includes:

1. **Profile Caching**: Stores user profiles with metadata
2. **Event Caching**: Stores Nostr events with efficient indexing
3. **Unpublished Event Queue**: Manages events pending publication
4. **Web of Trust Storage**: Maintains relationship scores

We will integrate this caching system across multiple components of our app to provide a better offline experience.

## Implementation Priorities

### 1. Profile Image Caching

**Files to Modify:**
- `components/UserAvatar.tsx`
- Create new: `lib/db/services/ProfileImageCache.ts`

**Functions to Implement:**
- `getProfileImageUri(pubkey, imageUrl)`: Get a cached image URI or download if needed
- `clearOldCache(maxAgeDays)`: Remove old cached images

**Integration Points:**
- Update `UserAvatar` to use the cache service
- Add cache invalidation based on profile updates

### 2. Publication Queue Service

**Files to Modify:**
- `lib/db/services/PublicationQueueService.ts`

**Functions to Enhance:**
- `queueEvent(event)`: Use NDK's unpublished events system
- `processQueue()`: Process events from NDK cache
- `getPendingEvents(limit)`: Get events from NDK cache
- `getPendingCount()`: Get count from NDK cache

**Migration Strategy:**
1. Add NDK cache support
2. Dual-write period
3. Migrate existing queue
4. Remove custom implementation

### 3. Social Feed Caching

**Files to Modify:**
- `lib/social/socialFeedService.ts`
- `lib/hooks/useSocialFeed.ts`

**Functions to Enhance:**
- `subscribeFeed(options)`: Check cache before subscription
- `getComments(eventId)`: Use cache for comments
- `resolveQuotedContent(event)`: Use cache for quoted content

**Benefits:**
- Immediate display of previously viewed content
- Reduced network requests
- Offline browsing of previously viewed feeds

### 4. Workout History

**Files to Modify:**
- `lib/db/services/UnifiedWorkoutHistoryService.ts`

**Functions to Enhance:**
- `getNostrWorkouts()`: Use NDK cache directly
- `importNostrWorkoutToLocal(eventId)`: Leverage cache for imports
- `subscribeToNostrWorkouts(pubkey, callback)`: Use cache for initial data

**Benefits:**
- Faster workout history loading
- Offline access to workout history
- Reduced network usage

### 5. Exercise Library

**Files to Modify:**
- `lib/db/services/ExerciseService.ts`
- `lib/hooks/useExercises.ts`

**Functions to Implement:**
- `getExercisesFromNostr()`: Use cache for exercises
- `getExerciseDetails(id)`: Get details from cache

**Benefits:**
- Offline access to exercise library
- Faster exercise loading

### 6. Workout Templates

**Files to Modify:**
- `lib/db/services/TemplateService.ts`
- `lib/hooks/useTemplates.ts`

**Functions to Enhance:**
- `getTemplateFromNostr(id)`: Use cache for templates
- `getTemplatesFromNostr()`: Get templates from cache

**Benefits:**
- Offline access to templates
- Faster template loading

### 7. Contact List & Following

**Files to Modify:**
- `lib/hooks/useContactList.ts`
- `lib/hooks/useFeedState.ts`

**Functions to Enhance:**
- `getContactList()`: Use cache for contact list
- `getFollowingList()`: Use cache for following list

**Benefits:**
- Offline access to contacts
- Faster contact list loading

### 8. General Media Cache

**Files to Create:**
- `lib/db/services/MediaCacheService.ts`

**Functions to Implement:**
- `cacheMedia(url, mimeType)`: Download and cache media
- `getMediaUri(url)`: Get cached media URI
- `clearOldCache(maxAgeDays)`: Remove old cached media

**Integration Points:**
- Profile banners
- Exercise images
- Other media content

## Implementation Approach

For each component, we will:

1. **Analyze Current Implementation**: Understand how data is currently fetched and stored
2. **Design Cache Integration**: Determine how to leverage NDK cache
3. **Implement Changes**: Modify code to use cache
4. **Test Offline Functionality**: Verify behavior when offline
5. **Measure Performance**: Compare before and after metrics

## Technical Considerations

### Cache Size Management

- Implement cache size limits
- Add cache eviction policies
- Prioritize frequently accessed data

### Cache Invalidation

- Track data freshness
- Implement TTL (Time To Live) for cached data
- Update cache when new data is received

### Error Handling

- Graceful fallbacks when cache misses
- Recovery from cache corruption
- Logging for debugging

## Success Metrics

- Reduced network requests
- Faster app startup time
- Improved offline experience
- Reduced data usage
- Better battery life

## Next Steps

1. Begin with Profile Image Cache implementation
2. Move to Publication Queue Service
3. Continue with remaining components in priority order