← reference

Workout Window Feature - Implementation Summary

Overview

The Workout Window feature is a complete accountability system that allows users to:

  • Set a 2-hour daily commitment window for activities (workout, meditation, reading, etc.)
  • Get matched with other users based on location and time windows
  • Form chains where users "pass the baton" to the next person
  • Join Red or Blue teams and compete in weekly battles
  • Check in with photos to verify completion
  • Earn battle chips for successful check-ins

Completed Components

1. Database Schema ✅

  • Migration: supabase/migrations/025_add_workout_window.sql
  • Tables:
    • workout_windows - User workout window configurations
    • workout_window_locations - User location data
    • workout_window_chains - Daily chain assignments
    • workout_window_squads - 3-person squad assignments
    • workout_window_checkins - User check-in records
    • workout_window_team_battles - Weekly battle records
    • workout_window_mosaic_status - Daily mosaic state

2. Backend API ✅

  • Routes: apps/backend/src/routes/workout-window.ts
  • Endpoints:
    • POST /api/workout-window/setup - Set up workout window
    • GET /api/workout-window/my-window - Get user's window
    • PUT /api/workout-window/update-location - Update location
    • GET /api/workout-window/chain/:date - Get chain for date
    • POST /api/workout-window/checkin - Submit check-in
    • GET /api/workout-window/checkin/:date - Get check-in status
    • POST /api/workout-window/cron/generate-chains - Cron endpoint
    • POST /api/workout-window/generate-chains - Manual generation
    • GET /api/workout-window/team-stats/:date - Team statistics

3. Core Services ✅

  • Chain Matching: apps/backend/src/services/workout-window/chain-matching.ts
    • Distance calculation (Haversine formula)
    • Time window matching
    • Team assignment (Red/Blue)
    • Squad creation (3-person teams)
  • Daily Chain Generator: apps/backend/src/services/workout-window/daily-chain-generator.ts
    • Generates chains for specific dates
    • Creates squads and assigns teams
    • Updates existing chains
  • Location Tracker: apps/backend/src/services/workout-window/location-tracker.ts
    • IP-based location detection
    • Coordinate-based location updates
    • Location retrieval

4. Web UI ✅

  • Setup Page: apps/frontend/src/app/dashboard/workout-window/page.tsx
    • Activity type selection
    • Time window picker
    • Location display
    • Timezone detection
  • Chain View: apps/frontend/src/app/dashboard/workout-window/chain/page.tsx
    • Before/after user display
    • Check-in status
    • Team color badge
    • Squad information
  • Check-In: apps/frontend/src/app/dashboard/workout-window/checkin/page.tsx
    • Photo upload with preview
    • Activity type display
    • Location capture
    • Duplicate prevention
  • Dashboard: apps/frontend/src/app/dashboard/workout-window/dashboard/page.tsx
    • Today's status
    • Team statistics
    • Quick actions
  • Navigation: Added to apps/frontend/src/components/layout/Navbar.tsx

5. Mobile UI ✅

  • Setup Screen: apps/mobile/src/screens/workout-window/WorkoutWindowSetupScreen.tsx
    • Activity selection with icons
    • Time window input
    • Custom activity input
    • Info section
  • Check-In Screen: apps/mobile/src/screens/workout-window/WorkoutWindowCheckInScreen.tsx
    • Camera integration (expo-image-picker)
    • Gallery selection
    • Location permissions (expo-location)
    • Photo preview
  • Navigation: Added to apps/mobile/src/navigation/MainNavigator.tsx
  • Settings Link: Added to apps/mobile/src/screens/settings/SettingsScreen.tsx

6. Tests ✅

  • Test Suite: apps/backend/src/routes/__tests__/workout-window.test.ts
  • Comprehensive tests for all endpoints
  • Mock Supabase client
  • Test coverage for edge cases

7. Documentation ✅

  • Cron Setup: docs/WORKOUT_WINDOW_CRON_SETUP.md
  • Storage Setup: docs/WORKOUT_WINDOW_STORAGE_SETUP.md
  • Implementation Plan: docs/WORKOUT_WINDOW_PLAN.md

Setup Requirements

1. Database Migration

Run the migration:

supabase migration up

2. Storage Bucket

Create the workout-checkins bucket in Supabase Storage:

  • Public bucket: Yes
  • File size limit: 10MB
  • Allowed MIME types: image/jpeg, image/png, image/gif, image/webp

See docs/WORKOUT_WINDOW_STORAGE_SETUP.md for detailed RLS policies.

3. Environment Variables

Add to backend .env:

WORKOUT_WINDOW_CRON_SECRET=your-secret-token-here

4. Cron Job Setup

Set up a daily cron job to generate chains:

  • Schedule: Daily at midnight UTC
  • Endpoint: POST /api/workout-window/cron/generate-chains
  • Header: x-cron-secret: your-secret-token-here

See docs/WORKOUT_WINDOW_CRON_SETUP.md for details.

5. Mobile Dependencies

Install required packages:

cd apps/mobile
npm install expo-image-picker expo-location

How It Works

1. User Setup

  1. User sets up workout window (activity type, time window, timezone)
  2. System captures user location (IP or GPS)
  3. Chains are automatically generated for today and tomorrow

2. Daily Chain Generation

  1. Cron job runs daily at midnight
  2. Algorithm matches users based on:
    • Location proximity (Haversine distance)
    • Time window sequence (before/after)
  3. Users assigned to Red or Blue teams
  4. 3-person squads created from chains

3. Check-In Process

  1. User completes activity during their window
  2. User uploads photo via web or mobile
  3. Photo stored in Supabase Storage
  4. Check-in recorded with:
    • Photo URL
    • Timestamp
    • Location (optional)
    • Status (pending → verified)
  5. Battle chips calculated:
    • Base: 1 chip
    • Bonus: +1 if chain continued (before user checked in)

4. Chain Visualization

  • Users see their "before" and "after" partners
  • Check-in status displayed for all chain members
  • Team color badge shows Red/Blue assignment
  • Squad information shows 3-person team

5. Team Competition

  • Red vs Blue teams compete daily
  • Stats tracked: completion rate, battle chips, members
  • Weekly battles (future feature)

Future Enhancements

Phase 2: Mosaic Generation

  • Daily low-poly mosaic image
  • Each section represents a participant
  • Clickable sections for details
  • Visual representation of chain success

Phase 3: Battle System

  • Weekly showdowns
  • Robot vs bad guy battles
  • Battle chips power robot
  • Team with most chips wins

Phase 4: Notifications

  • Notify next user in chain
  • Reminder notifications
  • Battle updates
  • Chain break alerts

Phase 5: Photo Verification

  • Automated verification (AI)
  • Manual admin verification
  • EXIF data extraction
  • Content moderation

Testing Checklist

  • User can set up workout window
  • Location is captured correctly
  • Chains are generated for new users
  • User can check in with photo
  • Chain view shows before/after users
  • Team stats display correctly
  • Battle chips calculated correctly
  • Mobile check-in works
  • Photo uploads to storage
  • RLS policies work correctly
  • Cron job generates chains daily

Known Limitations

  1. Squad Creation: Incomplete chains may create 2-person squads that need to be filled later
  2. Location Accuracy: IP-based location is approximate (city-level)
  3. Timezone Handling: Timezone conversion could be improved for global users
  4. Photo Verification: Currently manual, no automated verification
  5. Chain Matching: May not find matches for isolated users (low user density areas)

Support

For issues or questions:

  1. Check documentation in docs/ folder
  2. Review test files for usage examples
  3. Check backend logs for errors
  4. Verify storage bucket and RLS policies

Next Steps

  1. Set up storage bucket and RLS policies
  2. Configure cron job for daily chain generation
  3. Test with multiple users
  4. Monitor chain matching algorithm performance
  5. Gather user feedback for improvements
WORKOUT WINDOW IMPLEMENTATION SUMMARY — Docs | HiveJournal