docs: complete domain research

2026-02-15 22:48:57 +01:00
parent 58479807ec
commit 1041235449
5 changed files with 325 additions and 0 deletions
@@ -0,0 +1,59 @@
+# 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