Pitfalls: Workout App UX Improvements

Project: Gravl — PPL Workout Tracker Researched: 2026-02-15

Critical Pitfalls (Address in This Milestone)

1. Breaking Existing Logging Flow

Risk: Custom exercises don't integrate with program_exercise_id FK; progression and history break
Warning signs: Existing workout logs return empty after schema changes; progression graph gaps
Prevention: Add source_type column with default 'program'; never modify existing FK relationships; custom workouts use separate custom_workout_exercise_id
Phase: Database schema changes (early)

2. Competing State on Shared Program

Risk: If users modify program_exercises directly, it affects ALL users sharing program_id=1
Warning signs: One user's set count change appears for another user
Prevention: Never modify program_exercises table for per-user changes. Custom modifications create a new custom_workout that forks from the program. Program data stays read-only
Phase: Custom workout architecture

3. Backward Compatibility with Existing Logs

Risk: Existing logs assume fixed sets; schema changes break progression graphs and workout history
Warning signs: Historical workout data disappears or shows incorrectly
Prevention: source_type defaults to 'program'; all existing queries continue unchanged; new queries handle both source types
Phase: Database migration

4. Input Validation Gaps

Risk: No validation on negative reps, extreme weights, or invalid set numbers
Warning signs: Corrupted data in database; nonsensical progression suggestions
Prevention: Frontend: min=0 on inputs, stepper controls with bounds. Backend: validate before insert
Phase: Input UX fixes (Phase 1)

5. Mobile Layout Breakage

Risk: Extra buttons (add set, remove set, modify workout) break 600px layout; unusable on small phones
Warning signs: Horizontal scroll appears; buttons overlap; touch targets too small
Prevention: Design all new controls within existing 600px constraint first; test on 320px width; maintain 44px minimum touch targets
Phase: All UI changes

6. Scope Creep from "Add Set" to Full Program Builder

Risk: "Flexible sets" requirement grows into full periodization, program editor, template system
Warning signs: Conversations about "what if users want to plan a whole week" or "program templates"
Prevention: Strict scope: add/remove sets during a workout session. Custom workouts are simple exercise lists, not programs. No scheduling, no periodization
Phase: Scope discipline throughout

7. Unclear Completion State

Risk: Flexible sets make "workout complete" ambiguous — did they skip a set or just not add one?
Warning signs: Users feel guilty about "incomplete" workouts; confusion about what counts as done
Prevention: No "complete workout" enforcement. Each logged set is saved independently. Summary shows what was actually done, not what was "expected"
Phase: Workout flow UI

Gravl-Specific Risks

Hardcoded program_id=1

Dashboard directly fetches programs/1. Custom workouts that aren't program-linked will need their own navigation path in WorkoutSelectPage.

Upsert-Only Logging

Current /api/logs only updates/inserts. If user removes a set, there's no delete mechanism. Need DELETE endpoint for individual log entries.

Component-Level State Loss

Logs stored in React useState, not localStorage. If app closes mid-workout, all unlogged progress is lost. Consider auto-saving to localStorage as draft.

Single-File Backend

Adding new endpoints to backend/src/index.js (already 425 lines) increases risk of accidentally breaking existing routes. Test existing endpoints after each backend change.

Pre-Shipping Checklist

Existing workout logging still works identically
Historical workout data displays correctly
Progression suggestions unchanged for program workouts
All inputs validate (no negative reps, no negative weight)
Layout works on 320px-600px width range
Custom workouts don't affect other users' program data
Set add/remove persists correctly in database

4.2 KiB Raw Blame History