POWR/docs/design/WorkoutTab/HistoryTabEnhancementDesignDoc.md

History Tab Enhancement Design Document

Problem Statement

The current History tab provides basic workout tracking but lacks filtering, detailed views, and improved visualization features that would help users better navigate and understand their training history. Additionally, the app needs to better integrate with Nostr for workout sharing and synchronization across devices. Analytics and progress tracking features, which were initially considered for the History tab, have been moved to the Profile tab as they better align with documenting personal growth.

Requirements

Functional Requirements

• Enhanced workout history browsing with filtering and sorting
• Detailed workout view with complete exercise and set information
• Calendar view with improved visualization and interaction
• Export and sharing capabilities for workout data
• Search functionality across workout history
• Differentiation between local and Nostr-published workouts
• Ability to publish local workouts to Nostr
• Display of Nostr workouts not stored locally
• Integration with Profile tab for analytics and progress tracking

Non-Functional Requirements

• Performance optimization for large workout histories
• Responsive UI that works across device sizes
• Offline functionality for viewing history without network
• Consistent design language with the rest of the app
• Accessibility compliance
• Efficient data synchronization with Nostr relays

Design Decisions

1. Tab Structure Enhancement

Keep the existing History/Calendar structure, focusing on enhancing these views with better filtering, search, and visualization.

Rationale:

• Maintains simplicity of individual views
• Follows established patterns in fitness apps
• Allows specialized UI for each view type
• Analytics and progress tracking will be moved to the Profile tab for better user context

2. Authentication State Handling

Show only local workouts when the user is not authenticated with Nostr, with clear messaging about the benefits of logging in.

Rationale:

• Provides immediate value without requiring authentication
• Creates a clear upgrade path for users
• Simplifies initial implementation
• Follows progressive disclosure principles

3. Data Aggregation Strategy

Implement a dedicated analytics service that pre-processes workout data for visualization. This service will be shared with the Profile tab's analytics features.

Rationale:

• Improves performance by avoiding repeated calculations
• Enables complex trend analysis without UI lag
• Separates presentation logic from data processing
• Supports both history visualization and profile analytics

4. History Visualization Approach

Focus on providing clear, chronological views of workout history with rich filtering and search capabilities.

Rationale:

• Users need to quickly find specific past workouts
• Calendar view provides temporal context for training patterns
• Filtering by exercise, type, and other attributes enables targeted review
• Integration with Profile tab analytics provides deeper insights when needed

5. Nostr Integration Strategy

Implement a tiered approach to Nostr integration, starting with basic publishing capabilities in the MVP and expanding to full synchronization in future versions.

Rationale:

• Allows for incremental development and testing
• Prioritizes most valuable features for initial release
• Addresses core user needs first
• Builds foundation for more advanced features

6. Visual Indicators for Nostr Workouts

Use the app's primary purple color as a visual indicator for Nostr-published workouts, applied to strategic UI elements.

Rationale:

• Creates clear visual distinction between local and Nostr workouts
• Leverages existing brand color for positive association
• Provides consistent visual language across the app
• Enhances scannability of workout history

Technical Design

Visual Design for Nostr Integration

Workout Source Indicators

We will use the following visual indicators to clearly communicate workout source:

1. Local-only workouts: Standard card with gray icon
2. Nostr-published workouts:
   • Primary purple border or accent
   • Purple cloud icon
   • Optional purple title text
3. Nostr-only workouts (not stored locally):
   • Full purple background with white text
   • Cloud download icon for import action

Authentication State UI

When not authenticated:

• Show only local workouts
• Display a banner with login prompt
• Use the NostrLoginSheet component for consistent login experience
• Provide clear messaging about benefits of Nostr login

// Example authentication state handling
{!isAuthenticated ? (
  <View className="p-4 mb-4 border border-primary rounded-md">
    <Text className="text-foreground mb-2">
      Login with Nostr to access more features:
    </Text>
    <Text className="text-muted-foreground mb-4">
      • Sync workouts across devices
      • Back up your workout history
      • Share workouts with friends
    </Text>
    <Button 
      variant="purple" 
      onPress={() => setIsLoginSheetOpen(true)}
    >
      <Text className="text-white">Login with Nostr</Text>
    </Button>
  </View>
) : null}

Core Components

// Enhanced history service

// Enhanced workout history service
interface EnhancedWorkoutHistoryService extends WorkoutHistoryService {
  searchWorkouts(query: string): Promise<Workout[]>;
  filterWorkouts(filters: WorkoutFilters): Promise<Workout[]>;
  getWorkoutsByExercise(exerciseId: string): Promise<Workout[]>;
  exportWorkoutHistory(format: 'csv' | 'json'): Promise<string>;
  getWorkoutStreak(): Promise<StreakData>;
  
  // Nostr integration methods
  getWorkoutSyncStatus(workoutId: string): Promise<{
    isLocal: boolean;
    isPublished: boolean;
    eventId?: string;
    relayCount?: number;
  }>;
  publishWorkoutToNostr(workoutId: string): Promise<string>; // Returns event ID
}

// Nostr workout service (for future expansion)
interface NostrWorkoutHistoryService {
  // Fetch workouts from relays that aren't in local DB
  fetchNostrOnlyWorkouts(since?: Date): Promise<Workout[]>;
  
  // Merge local and Nostr workouts with deduplication
  getMergedWorkoutHistory(): Promise<Workout[]>;
  
  // Import a Nostr workout into local DB
  importNostrWorkoutToLocal(eventId: string): Promise<string>;
}

// New data structures
interface WorkoutStats {
  period: string;
  workoutCount: number;
  totalVolume: number;
  totalDuration: number;
  averageIntensity: number;
  exerciseDistribution: Record<string, number>;
}

interface ProgressPoint {
  date: number;
  value: number;
  workoutId: string;
}

interface WorkoutFilters {
  type?: TemplateType[];
  dateRange?: { start: Date; end: Date };
  exercises?: string[];
  tags?: string[];
  source?: ('local' | 'nostr' | 'both')[];
}

// Enhanced WorkoutCard props
interface EnhancedWorkoutCardProps extends WorkoutCardProps {
  source: 'local' | 'nostr' | 'both';
  publishStatus?: {
    isPublished: boolean;
    relayCount: number;
    lastPublished?: number;
  };
  onShare?: () => void;
  onImport?: () => void;
}

Database Schema Updates

-- Fix typo in service name first (WorkoutHIstoryService -> WorkoutHistoryService)

-- Add Nostr-related fields to completed_workouts table
ALTER TABLE completed_workouts ADD COLUMN nostr_event_id TEXT;
ALTER TABLE completed_workouts ADD COLUMN nostr_published_at INTEGER;
ALTER TABLE completed_workouts ADD COLUMN nostr_relay_count INTEGER DEFAULT 0;
ALTER TABLE completed_workouts ADD COLUMN source TEXT DEFAULT 'local';

-- Create table for tracking Nostr-only workouts (future expansion)
CREATE TABLE IF NOT EXISTS nostr_workouts (
  event_id TEXT PRIMARY KEY,
  pubkey TEXT NOT NULL,
  content TEXT NOT NULL,
  created_at INTEGER NOT NULL,
  kind INTEGER NOT NULL,
  tags TEXT NOT NULL,
  sig TEXT NOT NULL,
  last_seen INTEGER NOT NULL,
  relay_count INTEGER NOT NULL
);

Integration Points

• SQLite database for local storage
• Chart libraries for data visualization
• Share API for exporting workout data
• Nostr integration for social sharing and sync
• Calendar API for date handling
• NDK for Nostr relay communication

Implementation Plan

Phase 1: Foundation & Enhanced History View

1. Fix typo in WorkoutHistoryService filename
2. Implement workout detail view navigation
3. Add filtering and sorting to history list
4. Enhance WorkoutCard with more metrics
5. Implement search functionality
6. Add basic Nostr status indicators (local vs. published)
7. Improve calendar visualization with heatmap
8. Add day summary popups to calendar

Phase 2: Nostr Integration (MVP)

1. Update database schema to track Nostr event IDs and publication status
2. Implement visual indicators for workout source/status
3. Add basic publishing functionality for local workouts
4. Add filtering by source (local/published)

Phase 3: Export & Sharing

1. Add workout export functionality
2. Implement social sharing features
3. Create printable workout reports
4. Add data backup options

Phase 4: Integration with Profile Analytics

1. Implement data sharing with Profile tab analytics
2. Add navigation links to relevant analytics from workout details
3. Ensure consistent data representation between History and Profile tabs

Future Phases: Advanced Nostr Integration

1. Create NostrWorkoutHistoryService for fetching Nostr-only workouts
2. Implement workout importing functionality
3. Add background sync for Nostr workouts
4. Implement batch operations for publishing/importing
5. Add cross-device synchronization

UI Mockups

History Tab with Source Indicators

┌─────────────────────────────────────────┐
│ HISTORY                                 │
├─────────────────────────────────────────┤
│ ┌─────────────────────────────────────┐ │
│ │ MARCH 2025                          │ │
│ │                                     │ │
│ │ ┌─────────────────────────────────┐ │ │
│ │ │ Push Day 1             🔄 >     │ │ │
│ │ │ Friday, Mar 7                   │ │ │
│ │ │ ⏱️ 1h 47m  ⚖️ 9239 lb  🔄 120   │ │ │
│ │ │                                 │ │ │
│ │ │ Bench Press                     │ │ │
│ │ │ Incline Dumbbell Press          │ │ │
│ │ │ Tricep Pushdown                 │ │ │
│ │ └─────────────────────────────────┘ │ │
│ │                                     │ │
│ │ ┌─────────────────────────────────┐ │ │
│ │ │ Pull Day 1             📱 >     │ │ │
│ │ │ Wednesday, Mar 5                │ │ │
│ │ │ ⏱️ 1h 36m  ⚖️ 1396 lb  🔄 95    │ │ │
│ │ │                                 │ │ │
│ │ │ Lat Pulldown                    │ │ │
│ │ │ Seated Row                      │ │ │
│ │ │ Bicep Curl                      │ │ │
│ │ └─────────────────────────────────┘ │ │
│ │                                     │ │
│ └─────────────────────────────────────┘ │
│                                         │
│ ┌─────────────────────────────────────┐ │
│ │ FEBRUARY 2025                       │ │
│ │                                     │ │
│ │ ┌─────────────────────────────────┐ │ │
│ │ │ Leg Day 1             ☁️ >     │ │ │
│ │ │ Monday, Feb 28                  │ │ │
│ │ │ ⏱️ 1h 15m  ⚖️ 8750 lb  🔄 87    │ │ │
│ │ │                                 │ │ │
│ │ │ Squat                           │ │ │
│ │ │ Leg Press                       │ │ │
│ │ │ Leg Extension                   │ │ │
│ │ └─────────────────────────────────┘ │ │
└─────────────────────────────────────────┘

Legend:
🔄 - Local only
📱 - Published to Nostr
☁️ - From Nostr (not stored locally)

Workout Detail View with Sharing

┌─────────────────────────────────────────┐
│ < WORKOUT DETAILS                       │
├─────────────────────────────────────────┤
│ Push Day 1                              │
│ Friday, March 7, 2025                   │
│                                         │
│ ⏱️ 1h 47m  ⚖️ 9239 lb  🔄 120 reps      │
│                                         │
│ ┌─────────────────────────────────────┐ │
│ │ EXERCISES                           │ │
│ │                                     │ │
│ │ Bench Press                         │ │
│ │ 135 lb × 12                         │ │
│ │ 185 lb × 10                         │ │
│ │ 205 lb × 8                          │ │
│ │ 225 lb × 6                          │ │
│ │                                     │ │
│ │ Incline Dumbbell Press              │ │
│ │ 50 lb × 12                          │ │
│ │ 60 lb × 10                          │ │
│ │ 70 lb × 8                           │ │
│ │                                     │ │
│ │ Tricep Pushdown                     │ │
│ │ 50 lb × 15                          │ │
│ │ 60 lb × 12                          │ │
│ │ 70 lb × 10                          │ │
│ └─────────────────────────────────────┘ │
│                                         │
│ ┌─────────────────────────────────────┐ │
│ │ NOTES                               │ │
│ │ Felt strong today. Increased bench  │ │
│ │ press weight by 10 lbs.             │ │
│ └─────────────────────────────────────┘ │
│                                         │
│ ┌─────────────────────────────────────┐ │
│ │ 🔄 Local Only                       │ │
│ │                                     │ │
│ │ [Publish to Nostr]                  │ │
│ └─────────────────────────────────────┘ │
│                                         │
│ [Export Workout]                        │
└─────────────────────────────────────────┘

Note: Analytics Dashboard and Progress Tracking features have been moved to the Profile tab. See the Profile Tab Enhancement Design Document for details on these features.

Testing Strategy

Unit Tests

• Service method tests for data processing
• Component rendering tests
• Filter and search algorithm tests
• Chart data preparation tests
• Nostr event creation and parsing tests

Integration Tests

• End-to-end workout flow tests
• Database read/write performance tests
• UI interaction tests
• Cross-tab navigation tests
• Nostr publishing and retrieval tests

Future Considerations

Potential Enhancements

• AI-powered workout insights and recommendations
• Advanced periodization analysis
• Integration with wearable devices for additional metrics
• Video playback of recorded exercises
• Community benchmarking and anonymous comparisons
• Full cross-device synchronization via Nostr
• Collaborative workouts with friends

Advanced Nostr Integration (Future Epochs)

• Two-Way Synchronization:

  • Automatic sync of workouts between devices
  • Conflict resolution for workouts modified on multiple devices
  • Background sync with configurable frequency
  • Offline queue for changes made without connectivity

• Relay Selection & Management:

  • User-configurable relay preferences
  • Performance-based relay prioritization
  • Automatic relay discovery
  • Relay health monitoring and fallback strategies

• Enhanced Privacy Controls:

  • Granular sharing permissions for workout data
  • Private/public workout toggles
  • Selective metric sharing (e.g., share exercises but not weights)
  • Time-limited sharing options

• Data Portability & Backup:

  • Automated backup to preferred relays
  • Export/import of complete workout history
  • Migration tools between apps supporting the same Nostr standards
  • Archiving options for older workouts

• Social Features:

  • Workout sharing with specific users or groups
  • Collaborative workout planning
  • Training partner matching
  • Coach/client relationship management
  • Achievement sharing and celebrations

Known Limitations

• Performance may degrade with very large workout histories
• Complex analytics require significant processing
• Limited by available device storage
• Some features require online connectivity
• Nostr relay availability affects sync reliability
• Initial implementation will have limited cross-device sync capabilities
• Relay selection and management will be simplified in early versions

Integration with Profile Tab

The History tab will integrate with the Profile tab's analytics and progress tracking features to provide a cohesive user experience:

Data Flow

• The same underlying workout data will power both History views and Profile analytics
• The analytics service will process workout data for both tabs
• Changes in one area will be reflected in the other

Navigation Integration

• Workout detail views will include links to relevant analytics in the Profile tab
• The Profile tab's progress tracking will link back to relevant historical workouts
• Consistent data visualization will be used across both tabs

User Experience

• Users will use the History tab for finding and reviewing specific workouts
• Users will use the Profile tab for analyzing trends and tracking progress
• The separation provides clearer context for each activity while maintaining data consistency

References

• Workout Data Flow Specification
• Nostr Exercise NIP
• WorkoutHistoryService implementation
• NDK documentation
• Profile Tab Enhancement Design Document