React Native Feature Parity Plan - 2026 Update

Overview

This document outlines the plan to bring the React Native mobile app to feature parity with the web application, focusing on features added since the last major parity push. Workout Window mosaic image work is excluded as per requirements.

Analysis of Recent Frontend Updates

Features Added Since Last Parity Push

Based on analysis of the frontend codebase, the following major features have been added:

1. JQ AI Assistant & Analysis System

   • Daily/Weekly/Monthly note analysis with sleep, mood, and energy integration
   • Analysis page with calendar heatmap
   • Chatbot with analysis capabilities
   • JQ Daily Drops (personalized encouragement)

2. Sleep Tracking

   • Sleep entry creation and management
   • Sleep hours tracking
   • Integration with JQ analysis

3. Enhanced Mood & Energy Tracking

   • Energy level tracking (new)
   • Mood tracking enhancements
   • Integration with analysis and trends

4. JQ Bridge System

   • Connection management (create, edit, delete)
   • Invitation system (send, accept, view)
   • Permission management (granular sharing controls)
   • Bridge token-based JQ chat access
   • Sharing of sleep patterns, mood trends, and energy ratings

5. Encouragement Drops System

   • Drop sending (encouragement, media, science tidbits)
   • Drop templates library
   • Drops received view
   • Integration with Stream

6. Stream Enhancements

   • Sleep entries displayed in stream
   • Drop entries displayed in stream
   • Satisfaction entries displayed in stream
   • Action entries displayed in stream
   • Unified chronological view

7. Positive Note Display

   • Pulsing purple animation when loading
   • Enhanced UI/UX

8. Public Pages (Lower Priority)

   • Compare page
   • Features page updates
   • About JQ page updates
   • Homepage variant B updates

Current Mobile App Status

✅ Already Implemented

• Authentication (Sign In/Sign Up)
• Dashboard with journal entries
• Entry editor and detail views
• Notebooks (list, detail, editor)
• Goals (list, detail, editor)
• Stream view (basic)
• Settings screen
• WorkoutWindow (setup, check-in, dashboard, chain, mosaic, battle)
• Action button (floating)
• Satisfaction slider (floating)
• Positive note display (floating, but missing pulsing animation)
• DreamPro (dreams, detail, editor)
• Basic mood tracking in entry editor

❌ Missing Features (Need Implementation)

Phase 1: JQ Analysis System (HIGH PRIORITY)

1.1 Analysis Page Screen

Priority: High

• Analysis Screen (screens/analysis/AnalysisScreen.tsx)
  • Display list of analyses (daily, weekly, monthly)
  • Filter by granularity (day/week/month)
  • Calendar heatmap visualization
  • Analysis detail view with:
    • Summary
    • Mood trends with charts
    • Topics
    • Patterns
    • Recommendations
    • Insights (gratitude, challenges, goals, achievements)
    • Sleep and energy data integration
  • Trigger new analysis button
  • Analysis status indicator (idle/processing/completed)

1.2 Analysis API Integration

Priority: High

• Update services/api.ts with analysis endpoints:

  • GET /api/chat/analyses - Get all analyses
  • POST /api/chat/analyze - Trigger new analysis
  • GET /api/chat/analysis-status - Check analysis status
  • GET /api/chat/heatmap-data - Get heatmap data

• Add TypeScript interfaces:

  interface NoteAnalysis {
    id: string
    analysis_date: string
    granularity?: 'day' | 'week' | 'month'
    summary: string
    mood_trends: {
      most_common: string[]
      trends: Array<{ date: string; mood: string }>
    }
    mood_energy_trends?: {
      average_satisfaction: number
      average_energy: number | null
      trends: Array<{ date: string; satisfaction: number; energy: number | null }>
      recommendations: string
    }
    topics: string[]
    patterns: string[]
    recommendations: string
    insights: {
      gratitude?: string[]
      challenges?: string[]
      goals?: string[]
      achievements?: string[]
    }
    entry_count: number
    created_at: string
    updated_at: string
  }
  

1.3 Calendar Heatmap Component

Priority: Medium

• CalendarHeatmap Component (components/analysis/CalendarHeatmap.tsx)
  • Display calendar grid
  • Color intensity based on entry count
  • Tap to view analysis for date
  • Responsive design for mobile

1.4 Navigation Integration

Priority: Medium

• Add Analysis route to MainNavigator.tsx
• Add Analysis link to Settings or Dashboard
• Add Analysis tab (optional)

Phase 2: Sleep Tracking (HIGH PRIORITY)

2.1 Sleep Entry Creation

Priority: High

• Sleep Entry Component (components/sleep/SleepEntryForm.tsx)

  • Hours slept input (decimal)
  • Date picker
  • Optional notes
  • Save/Cancel actions

• Sleep Entry Screen (screens/sleep/SleepEntryScreen.tsx)

  • Full-screen sleep entry form
  • Navigation from dashboard or satisfaction slider

2.2 Sleep Display & Management

Priority: High

• Update EntryDetailScreen.tsx to handle sleep entries
• Display sleep entries in Dashboard
• Display sleep entries in Stream (already in web)
• Sleep entry editing and deletion

2.3 Sleep API Integration

Priority: High

Corrected 2026-07-28. The endpoints and interface originally specified here (/api/sleep-entries, fetch/update by id, a notes field, an updated_at column) do not exist and never did. Mobile was built to this spec and every sleep call 404'd. Below is the real contract — see routes/sleep.ts and migration 023.

• Update services/api.ts with sleep endpoints:

  • GET /api/sleep?limit&offset - Get sleep entries ({ sleep_entries }, no total)
  • GET /api/sleep/date/:date - Get one night ({ sleep_entry: … | null })
  • POST /api/sleep - Upsert on (user_id, sleep_date); there is no PUT /:id
  • DELETE /api/sleep/:id - Delete sleep entry

• Add TypeScript interfaces:

  interface SleepEntry {
    id: string
    user_id: string
    sleep_date: string   // YYYY-MM-DD, unique per user — this is the key
    hours_slept: number  // 0–12, CHECK-constrained
    created_at: string
  }
  

2.4 Satisfaction Slider Integration

Priority: Medium

• Update SatisfactionSlider.tsx to include sleep entry option
• Add "Log Sleep" button to satisfaction slider
• Navigate to sleep entry screen

Phase 3: Enhanced Mood & Energy Tracking (HIGH PRIORITY)

3.1 Energy Tracking

Priority: High

• Update EntryEditorScreen.tsx to include energy selector

  • Energy level picker (1-10 scale or similar)
  • Visual energy indicator
  • Save energy with entry

• Update entry display to show energy level

• Add energy to entry detail view

3.2 Mood & Energy Trends

Priority: Medium

• Display mood/energy trends in Analysis screen
• Mood/energy charts visualization
• Integration with analysis recommendations

3.3 API Updates

Priority: High

• Update entry creation/update to include energy field
• Ensure backend supports energy in entries

Phase 4: JQ Bridge System (HIGH PRIORITY)

4.1 Bridge Connection Management

Priority: High

• JQ Bridge Screen (screens/jq-bridge/JQBridgeScreen.tsx)

  • List of connections
  • Add new connection form
  • Edit connection permissions
  • Delete connection
  • Connection status indicators

• Connection Editor Component (components/jq-bridge/ConnectionEditor.tsx)

  • Contact email/name input
  • Connection type selector (family/friend/professional/healthcare)
  • Permission toggles (summary, mood_trends, topics, patterns, recommendations, insights)
  • Generate invitation link

4.2 Invitation System

Priority: High

• Invitations Screen (screens/jq-bridge/InvitationsScreen.tsx)

  • List of pending invitations
  • Accept/decline actions
  • View invitation details
  • Accepted invitations list

• My Connections Screen (screens/jq-bridge/MyConnectionsScreen.tsx)

  • List of active connections
  • View shared data
  • Chat with JQ (bridge token)
  • Connection details and permissions

4.3 Bridge Chat Integration

Priority: High

• Update Chatbot component to support bridge tokens
• Load bridge connection context
• Display bridge connection info in chat
• Limit chat scope based on permissions

4.4 Bridge API Integration

Priority: High

• Update services/api.ts with bridge endpoints:

  • GET /api/jq-bridge/connections - Get connections
  • POST /api/jq-bridge/connections - Create connection
  • PUT /api/jq-bridge/connections/:id - Update connection
  • DELETE /api/jq-bridge/connections/:id - Delete connection
  • PUT /api/jq-bridge/connections/:id/permissions - Update permissions
  • GET /api/jq-bridge/invitations - Get invitations
  • POST /api/jq-bridge/accept - Accept invitation
  • GET /api/jq-bridge/my-connections - Get my connections

• Add TypeScript interfaces:

  interface BridgeConnection {
    id: string
    contact_email: string
    contact_name: string | null
    connection_type: 'family' | 'friend' | 'professional' | 'healthcare'
    status: 'pending' | 'accepted' | 'declined'
    invitation_token: string
    invitation_sent_at: string | null
    accepted_at: string | null
    created_at: string
    profiles?: {
      id: string
      full_name: string | null
      email: string
      avatar_url: string | null
    }
    permissions?: Array<{
      id: string
      permission_type: string
      enabled: boolean
    }>
  }
  

4.5 Navigation Integration

Priority: Medium

• Add JQ Bridge routes to MainNavigator.tsx
• Add JQ Bridge link to Settings
• Add JQ Bridge section in Dashboard (optional)

Phase 5: Encouragement Drops System (MEDIUM PRIORITY)

5.1 Drop Sending

Priority: Medium

• Drop Sender Component (components/drops/DropSender.tsx)

  • Drop type selector (encouragement, media, science_tidbit)
  • Template library browser
  • Custom drop input
  • Recipient selection
  • Remaining drops counter
  • Send action

• Drop Templates Screen (screens/drops/DropTemplatesScreen.tsx)

  • Browse approved templates
  • Filter by type
  • Search functionality
  • Usage count display

5.2 Drops Received

Priority: Medium

• Drops Received Screen (screens/drops/DropsReceivedScreen.tsx)
  • List of drops received
  • Filter by type
  • Sender information
  • Timestamp
  • Read/unread status
  • Link to associated entry (if any)

5.3 Stream Integration

Priority: Medium

• Update StreamScreen.tsx to show drop entries

  • Display drops in chronological order
  • Show drop type indicators
  • Show sender information
  • Mark drops as read when viewed

• Add drop sending option from Stream

  • Drop button on entry cards
  • Open drop sender modal

5.4 Drop Counter Component

Priority: Low

• Drop Counter Component (components/drops/DropCounter.tsx)
  • Display remaining drops for today
  • Show in navigation or header
  • Update in real-time

5.5 Drops API Integration

Priority: Medium

• Update services/api.ts with drops endpoints:

  • GET /api/encouragement-drops/templates - Get templates
  • POST /api/encouragement-drops/send - Send drop
  • GET /api/encouragement-drops/received - Get received drops
  • PUT /api/encouragement-drops/:id/read - Mark as read
  • GET /api/encouragement-drops/balance - Get drops balance

• Add TypeScript interfaces:

  interface DropTemplate {
    id: string
    content: string
    drop_type: 'encouragement' | 'media' | 'science_tidbit'
    approved: boolean
    usage_count: number
  }
  
  interface Drop {
    id: string
    sender_id: string
    recipient_id: string
    content: string
    drop_type: 'encouragement' | 'media' | 'science_tidbit'
    media_url?: string | null
    template_id?: string | null
    entry_id?: string | null
    read_at: string | null
    created_at: string
    sender_name?: string
  }
  

Phase 6: Stream Enhancements (MEDIUM PRIORITY)

6.1 Enhanced Stream Display

Priority: Medium

• Update StreamScreen.tsx to handle all entry types:

  • Journal entries (existing)
  • Sleep entries (new)
  • Drop entries (new)
  • Satisfaction entries (new)
  • Action entries (new)

• Entry type indicators:

  • Sleep entry badge/icon
  • Drop entry badge/icon
  • Satisfaction entry badge/icon
  • Action entry badge/icon

• Unified chronological sorting

• Entry type filtering (optional)

6.2 Stream API Updates

Priority: Medium

• Update Stream API call to fetch all entry types:

  • Journal entries
  • Sleep entries
  • Drops (read only)
  • Satisfaction entries
  • Action entries

• Merge and sort by created_at

• Handle entry type-specific display logic

Phase 7: Positive Note Display Enhancement (LOW PRIORITY)

7.1 Pulsing Animation

Priority: Low

• Update PositiveNoteDisplay.tsx to add pulsing purple animation
• Match web app animation style
• Animation triggers when loading note

Phase 8: Chatbot Integration (HIGH PRIORITY)

8.1 Chatbot Component

Priority: High

• Chatbot Component (components/chat/Chatbot.tsx)
  • Chat interface
  • Message history
  • Send messages
  • Analysis integration
  • Bridge token support
  • Conversation management

8.2 Chatbot API Integration

Priority: High

• Update services/api.ts with chatbot endpoints:
  • POST /api/chat/message - Send message
  • GET /api/chat/conversations - Get conversations
  • GET /api/chat/conversations/:id - Get conversation
  • POST /api/chat/conversations - Create conversation
  • GET /api/chat/settings - Get chatbot settings
  • PUT /api/chat/settings - Update chatbot settings

8.3 Chatbot Navigation

Priority: Medium

• Floating chatbot button (similar to web)
• Chatbot modal/sheet
• Minimize/maximize functionality

Phase 9: UI/UX Polish (LOW PRIORITY)

9.1 Component Consistency

Priority: Low

• Match web app color schemes
• Consistent spacing and typography
• Dark mode support (if not already implemented)

9.2 Navigation Improvements

Priority: Low

• Add bottom tabs for major features (optional)
• Improve navigation flow
• Add quick actions

Implementation Order

Sprint 1: Core Analysis & Sleep (Week 1-2)

1. Sleep entry creation and management
2. Analysis screen and API integration
3. Calendar heatmap component
4. Sleep integration with Stream

Sprint 2: Energy Tracking & Analysis Integration (Week 2-3)

1. Energy tracking in entry editor
2. Mood/energy trends in analysis
3. Analysis detail view enhancements
4. Integration with existing mood tracking

Sprint 3: JQ Bridge Core (Week 3-4)

1. Bridge connection management
2. Invitation system
3. Bridge API integration
4. Navigation integration

Sprint 4: JQ Bridge Chat & Drops (Week 4-5)

1. Chatbot component with bridge support
2. Bridge token handling
3. Encouragement drops sending
4. Drops received view

Sprint 5: Stream & Polish (Week 5-6)

1. Stream enhancements (all entry types)
2. Drop integration with Stream
3. Positive note animation
4. UI/UX polish
5. Testing and bug fixes

Technical Considerations

Dependencies

• Verify required packages:
  • react-native-calendars or similar (for heatmap)
  • react-native-chart-kit or victory-native (for charts)
  • @react-native-community/datetimepicker (for date/time pickers)
  • react-native-svg (for charts/visualizations)

Performance

• Implement pagination for long lists (analyses, connections, drops)
• Use React Query for caching and optimistic updates
• Optimize image loading in Stream
• Lazy load components where appropriate

Offline Support

• Consider offline-first approach for viewing data
• Queue actions when offline
• Sync when connection restored

Testing

• Unit tests for new components
• Integration tests for API calls
• E2E tests for critical flows
• Test on both iOS and Android
• Test on different screen sizes

File Structure

apps/mobile/src/
├── screens/
│   ├── analysis/
│   │   └── AnalysisScreen.tsx
│   ├── sleep/
│   │   └── SleepEntryScreen.tsx
│   ├── jq-bridge/
│   │   ├── JQBridgeScreen.tsx
│   │   ├── InvitationsScreen.tsx
│   │   └── MyConnectionsScreen.tsx
│   └── drops/
│       ├── DropTemplatesScreen.tsx
│       └── DropsReceivedScreen.tsx
├── components/
│   ├── analysis/
│   │   └── CalendarHeatmap.tsx
│   ├── sleep/
│   │   └── SleepEntryForm.tsx
│   ├── jq-bridge/
│   │   └── ConnectionEditor.tsx
│   ├── drops/
│   │   ├── DropSender.tsx
│   │   └── DropCounter.tsx
│   └── chat/
│       └── Chatbot.tsx
└── services/
    └── api.ts (updated with new endpoints)

Success Criteria

• All JQ analysis features available on mobile
• Sleep tracking fully functional
• Energy tracking integrated
• JQ Bridge system complete
• Encouragement Drops system complete
• Stream shows all entry types
• Chatbot with bridge support working
• UI/UX matches web app quality
• Performance is acceptable on both iOS and Android
• All features tested and working

Notes

• Prioritize features based on user feedback and usage patterns
• Consider mobile-specific UX improvements (e.g., swipe gestures, pull-to-refresh)
• Ensure accessibility (screen readers, keyboard navigation)
• Follow React Native best practices and design patterns
• Maintain consistency with existing mobile app design language
• Workout Window mosaic image work is explicitly excluded from this plan