73 lines
4.2 KiB
Markdown
73 lines
4.2 KiB
Markdown
# 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
|