gravl/.planning/research/SUMMARY.md

Research Summary: Workout UX Improvements

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

Key Findings

Stack

• Keep existing React 18 + Vite + Express + PostgreSQL stack
• Add only: react-hook-form + zod + @hookform/resolvers (~38KB gzipped)
• Build custom stepper input component (no library needed)
• Do NOT add: UI frameworks, Redux, TanStack Query, Framer Motion
• CSS-only fix for touch targets: min 44px height, 16px font-size prevents iOS zoom

Table Stakes (Must Ship)

• Input validation: no negative reps/weights, proper number constraints
• Weight unit display (kg suffix visible in input)
• Mobile-optimized input layout (larger touch targets)
• Add/remove sets per exercise
• Pre-fill last workout's values for reference

Differentiators (Should Ship)

• Custom workout builder (pick exercises, save as template)
• Modify program workouts (fork to custom)
• Stepper inputs for rapid logging (+/- buttons)

Watch Out For

1. Don't break existing flow — program workout logging must stay identical
2. Don't modify shared program data — fork to custom_workout for per-user changes
3. Don't let scope creep — "add set" ≠ "full program builder"
4. Don't break mobile layout — all new controls must fit 600px width
5. Backward compat — existing workout_logs must keep working with new schema

Architecture Decision

Dual data path:

• Program workouts (existing, read-only) — unchanged
• Custom workouts (new) — user-created, flexible sets, stored in new tables

New tables: custom_workouts, custom_workout_exercises Enhanced: workout_logs gets source_type column (default 'program')

Suggested Build Order

1. Input UX fixes (validation, units, stepper, layout) — no backend changes
2. Flexible sets (local state + backend accepts variable set count)
3. Exercise list endpoint (GET /api/exercises for search)
4. Custom workout CRUD (new tables + endpoints)
5. Custom workout builder UI (frontend page)
6. Modify program workout (fork program → custom)

Each phase is independently shippable. Phase 1 delivers immediate UX value with zero risk.

Research Files

• STACK.md — Technology recommendations and what to avoid
• FEATURES.md — Feature categorization (table stakes vs differentiators)
• ARCHITECTURE.md — Schema design, component structure, data flow
• PITFALLS.md — 7 critical pitfalls with prevention strategies