POWR/docs/design/cache-management.md

NDK Mobile Cache Integration Plan

Overview

This document outlines the comprehensive strategy for leveraging the NDK mobile SQLite cache system throughout the POWR app to improve offline functionality, reduce network usage, and enhance performance.

Goals

1. Improve Offline Experience: Allow users to access critical app features even when offline
2. Reduce Network Usage: Minimize data consumption by caching frequently accessed data
3. Enhance Performance: Speed up the app by reducing network requests
4. Maintain Data Freshness: Implement strategies to keep cached data up-to-date

Implementation Components

1. Profile Image Caching

Status: Implemented

The ProfileImageCache service downloads and caches profile images locally, providing offline access and reducing network usage.

// Key features of ProfileImageCache
- Local storage of profile images in the app's cache directory
- Automatic fetching and caching of images when needed
- Age-based cache invalidation (24 hours by default)
- Integration with UserAvatar component for seamless usage

Integration Points:

• UserAvatar component uses the cache for all profile images
• EnhancedSocialPost component uses UserAvatar for profile images in the feed
• NDK initialization sets the NDK instance in the ProfileImageCache service

2. Publication Queue Service

Status: Implemented

The PublicationQueueService allows events to be created and queued when offline, then published when connectivity is restored.

// Key features of PublicationQueueService
- Persistent storage of unpublished events
- Automatic retry mechanism when connectivity is restored
- Priority-based publishing
- Status tracking for queued events

Integration Points:

• Social posting
• Workout publishing
• Template sharing

3. Social Feed Caching

Status: Implemented

The SocialFeedCache service caches social feed events locally, allowing users to browse their feed even when offline.

// Key features of SocialFeedCache
- SQLite-based storage of feed events
- Feed-specific caching (following, POWR, global)
- Time-based pagination support
- Automatic cleanup of old cached events

Integration Points:

• useSocialFeed hook uses the cache when offline
• SocialFeedService manages the cache and provides a unified API
• Feed components display cached content with offline indicators

4. Workout History

Status: Implemented

The UnifiedWorkoutHistoryService provides access to workout history both locally and from Nostr, with offline support.

// Key features of workout history caching
- Local storage of all workout records
- Synchronization with Nostr when online
- Conflict resolution for workouts created offline
- Comprehensive workout data including exercises, sets, and metadata

Integration Points:

• History tab displays cached workout history
• Workout completion flow saves to local cache first
• Background synchronization with Nostr

5. Exercise Library

Status: Implemented

The ExerciseService maintains a local cache of exercises, allowing offline access to the exercise library.

// Key features of exercise library caching
- Complete local copy of exercise database
- Periodic updates from Nostr when online
- Custom exercise creation and storage
- Categorization and search functionality

Integration Points:

• Exercise selection during workout creation
• Exercise details view
• Exercise search and filtering

6. Workout Templates

Status: Implemented

The TemplateService provides offline access to workout templates through local caching.

// Key features of template caching
- Local storage of user's templates
- Synchronization with Nostr templates
- Favorite templates prioritized for offline access
- Template versioning and updates

Integration Points:

• Template selection during workout creation
• Template management in the library
• Template sharing and discovery

7. Contact List & Following

Status: Implemented

The system caches the user's contact list and following relationships for offline access.

// Key features of contact list caching
- Local storage of followed users
- Periodic updates when online
- Integration with NDK's contact list functionality
- Support for NIP-02 contact lists

Integration Points:

• Following feed generation
• User profile display
• Social interactions

8. General Media Cache

Status: Implemented

A general-purpose media cache for other types of media used in the app.

// Key features of general media cache
- Support for various media types (images, videos, etc.)
- Size-limited cache with LRU eviction
- Content-addressable storage
- Automatic cleanup of unused media

Integration Points:

• Article images in the feed
• Exercise demonstration images
• App assets and resources

Technical Implementation

NDK Integration

The NDK mobile adapter provides built-in SQLite caching capabilities that we leverage throughout the app:

// Initialize NDK with SQLite cache adapter
const cacheAdapter = new NDKCacheAdapterSqlite('powr', 1000);
await cacheAdapter.initialize();

const ndk = new NDK({
  cacheAdapter,
  explicitRelayUrls: DEFAULT_RELAYS,
  enableOutboxModel: true,
  autoConnectUserRelays: true,
  clientName: 'powr',
});

Connectivity Management

The ConnectivityService monitors network status and triggers appropriate cache behaviors:

// Key features of ConnectivityService
- Real-time network status monitoring
- Callback registration for connectivity changes
- Automatic retry of failed operations when connectivity is restored
- Bandwidth-aware operation modes

Cache Invalidation Strategies

Different types of data have different invalidation strategies:

1. Time-based: Profile images, feed events
2. Version-based: Exercise library, templates
3. Manual: User-triggered refresh
4. Never: Historical workout data

User Experience Considerations

Offline Indicators

The app provides clear visual indicators when operating in offline mode:

• Global offline indicator in the header
• Feed-specific offline state components
• Disabled actions that require connectivity
• Queued action indicators

Transparent Sync

Synchronization happens transparently in the background:

• Automatic publishing of queued events when connectivity is restored
• Progressive loading of fresh content when coming online
• Prioritized sync for critical data

Data Freshness

The app balances offline availability with data freshness:

• Age indicators for cached content
• Pull-to-refresh to force update when online
• Background refresh of frequently accessed data

Testing Strategy

Comprehensive testing ensures the cache system works reliably:

1. Unit Tests: Individual cache services
2. Integration Tests: Interaction between cache and UI components
3. Offline Simulation: Testing app behavior in offline mode
4. Performance Testing: Measuring cache impact on app performance
5. Edge Cases: Testing cache behavior with limited storage, connectivity issues, etc.

Future Enhancements

Potential future improvements to the caching system:

1. Selective Sync: User-configurable sync preferences
2. Compression: Reducing cache size through compression
3. Encryption: Enhancing security of cached data
4. Analytics: Usage patterns to optimize caching strategy
5. Cross-device Sync: Synchronizing cache across user devices

Conclusion

The NDK Mobile Cache Integration provides a robust foundation for offline functionality in the POWR app, significantly improving the user experience in limited connectivity scenarios while reducing network usage and enhancing performance.