HyperTrack - Intelligent Workout Tracker
A science-based hypertrophy training app with intelligent auto-regulation, built with Next.js 14, Supabase, and TypeScript.
Features
- AI Coaching: Get personalized training advice based on your actual workout data, body composition, and training phase
- Volume Tracking: Monitor sets per muscle group against personalized MEV/MAV/MRV landmarks
- Auto Progression: Intelligent weight and rep recommendations based on your performance
- Fatigue Management: Pre-workout readiness checks and smart deload recommendations
- Plateau Detection: Identify stalled exercises and get actionable suggestions
- Exercise Library: 50+ exercises with form cues, common mistakes, and setup notes
- Body Composition Tracking: DEXA scan tracking with FFMI calculations and regional analysis
- Strength Calibration: Benchmark lift testing with percentile rankings
Tech Stack
- Framework: Next.js 14 (App Router)
- Language: TypeScript (strict mode)
- Styling: TailwindCSS with custom design system
- Database: Supabase (PostgreSQL + Auth)
- State Management: Zustand
- Charts: Recharts
Getting Started
Prerequisites
- Node.js 18+
- Docker (for local Supabase)
Installation
- Clone the repository:
git clone <repo-url>
cd workout-app
- Install dependencies:
npm install
- Start local Supabase:
npx supabase start
- Copy environment variables:
cp .env.local.example .env.local
- Update
.env.local with your Supabase and API credentials (from supabase start output):
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
# For AI Coaching feature (Elite tier) - uses xAI Grok
XAI_API_KEY=your-xai-api-key
# Note: Other AI features (nutrition, label scanning, progress photos)
# may use ANTHROPIC_API_KEY if configured separately
- Run database migrations:
npx supabase db push
- Seed the exercise library:
npx supabase db reset
- Start the development server:
npm run dev
Open http://localhost:3000 to see the app.
Project Structure
/app # Next.js App Router pages
/(auth) # Auth routes (login, register)
/(dashboard) # Protected dashboard routes
/components # React components
/ui # Base UI components
/workout # Workout-specific components
/analytics # Charts and analytics
/hooks # Custom React hooks
/lib # Utilities and Supabase client
/services # Pure business logic
progressionEngine.ts # Auto-progression calculations
fatigueEngine.ts # Readiness and fatigue tracking
volumeTracker.ts # Weekly volume calculations
plateauDetector.ts # Plateau detection algorithms
exerciseSwapper.ts # Exercise swap suggestions
/stores # Zustand state stores
/types # TypeScript interfaces
/supabase # Database migrations and seeds
Key Concepts
Volume Landmarks
- MEV (Minimum Effective Volume): Minimum sets to maintain muscle
- MAV (Maximum Adaptive Volume): Optimal training zone
- MRV (Maximum Recoverable Volume): Upper limit before excessive fatigue
Progression Hierarchy
- Load progression: Increase weight when hitting rep targets
- Rep progression: Add reps before increasing weight
- Set progression: Add sets within mesocycle
- Technique progression: Maintain for consolidation
Set Quality Classification
- Junk: RPE ≤ 5 (too easy, not stimulative)
- Effective: RPE 6-7 (contributing to volume)
- Stimulative: RPE 7.5-9.5 (optimal for hypertrophy)
- Excessive: RPE 10 (may impair recovery)
Database Schema
The app uses these main tables:
users - User profiles with preferences and volume landmarksexercises - Exercise library with metadatamesocycles - Training blocks (4-8 weeks)workout_sessions - Individual workoutsexercise_blocks - Exercises within a session with targetsset_logs - Logged sets with quality classificationexercise_performance_snapshots - Historical performance for progress trackingplateau_alerts - Detected plateaus with suggestionstraining_phases - Cut/bulk/maintain phase tracking with goalsai_coaching_conversations - AI coaching conversation historydexa_scans - Body composition trackingcalibrated_lifts - Strength benchmarks with percentile rankings
License
MIT
