gymflow/specs/requirements.md

GymFlow Application Requirements Specification

1. Introduction

This document serves as the authoritative source of truth for the GymFlow application functionality. It is derived from a deep analysis of the production codebase (React frontend + Node.js/Prisma backend). These requirements are intended to guide future development and serve as the basis for automated test generation (Playwright).

2. System Actors

• Guest: An unauthenticated user (restricted to Login/Register).
• User: A standard authenticated user with access to tracking, plans, and capabilities.
• Admin: A super-user with additional privileges to manage other users (block, delete, reset passwords).

---

3. Functional Requirements

3.1. Authentication & Integrity

The system relies on JWT-based authentication.

• 3.1.1 Login
  • Input: Email, Password.
  • Logic:
    • Must validate email existence.
    • Must validate password matches hash.
    • Block Check: Must prevent login if User.isBlocked is true, returning a 403 error.
  • UI:
    • Show "Invalid credentials" on failure.
    • Redirect to Tracker upon success.
    • Language Toggle: User must be able to switch between English (EN) and Russian (RU) before logging in.
• 3.1.2 Registration
  • Input: Email, Password.
  • Logic:
    • Email must be unique.
    • Creates a UserProfile with default values (e.g., default weight 70kg) upon account creation.
    • Sets isFirstLogin to true.
• 3.1.3 First-Time Setup (Password Change)
  • Trigger: If User.isFirstLogin is true.
  • Requirement: User must be forced to change password immediately after initial login.
  • Effect: Updates User.password and sets isFirstLogin to false.
• 3.1.4 Profile Management
  • Fields: Weight, Height, Gender, Birth Date.
  • Logic:
    • Updates to UserProfile table.
    • Dates are handled as ISO strings or timestamps.

3.2. Workout Management (Plans)

Users can structure their training via Plans.

• 3.2.1 Plan Creation/Editing
  • Data: Name (required), Description (optional).
  • Exercises:
    • User selects exercises from the global/personal library.
    • Ordering: Exercises must be ordered (0-indexed).
    • Weighted Flag: specific exercises in a plan can be marked as isWeighted (visual indicator).
  • Logic: Supports reordering capabilities via drag-and-drop in UI.
• 3.2.2 Plan Deletion
  • Standard soft or hard delete (Cascades to PlanExercises).

3.3. Exercise Library

• 3.3.1 Exercise Types The system supports distinct exercise types which dictate valid data entry fields:
  • STRENGTH: Requires Weight (kg) and Reps.
  • BODYWEIGHT: Requires Reps (and optional added Weight).
  • CARDIO: Requires Duration (s) and Distance (m).
  • STATIC: Requires Duration (s).
  • HIGH_JUMP: Requires Height (cm).
  • LONG_JUMP: Requires Distance (m).
  • PLYOMETRIC: Requires Reps.
• 3.3.2 Custom Exercises
  • User can create new exercises.
  • Unilateral Flag: Boolean flag isUnilateral. If true, sets recorded for this exercise can specify a side (LEFT/RIGHT).
  • Bodyweight %: For bodyweight-based calculations.

3.4. Workout Tracking (The "Tracker")

The core feature. States: Idle, Active Session, Sporadic Mode.

• 3.4.1 Active Session (Standard)
  • Initiation:
    • Can start "Free Workout" (no plan).
    • Can start from a "Plan".
    • Input: User confirms current Body Weight before starting.
    • Constraint: User cannot have more than one active standard session (where endTime is null). API returns 400 if one exists.
  • The "Active" State:
    • Persistence: Session remains active in DB if browser is closed. GET /sessions/active restores state.
    • Timer: Client-side logic calculates now - startTime.
  • Logging Sets:
    • Input: Exercise, Metrics (Weight/Reps/etc. based on Type), Side (if unilateral).
    • Smart Matching: If a Plan is active, the system attempts to match the logged set to the current step in the plan based on the exercise ID and the number of sets already performed vs. planned.
    • Response: Returns the created set and the activeExerciseId (for UI to auto-advance focus in plan).
  • Session Termination:
    • Finish: Updates endTime to now.
      • Profile Sync: If the session had a userBodyWeight set, it updates the UserProfile.weight.
    • Quit (No Save):
      • Destructive Action: Hard deletes the WorkoutSession and all associated WorkoutSets from the DB.
• 3.4.2 Active Session (Quick Log)
  • Concept: A special session type (QUICK_LOG) that aggregates all sporadic sets for a single day.
  • Logic:
    • GET /sessions/quick-log: Finds strictly one session for the current calendar day (00:00-23:59 local server time) of type QUICK_LOG.
    • POST /sessions/quick-log/set:
      • Finds OR Creates the daily Quick Log session.
      • Appends the set.
  • UI: Separate "Sporadic Mode" view specialized for fast, one-off entries without a timer or plan context.

3.5. History & Analysis

• 3.5.1 Session History
  • Displays all finished sessions.
  • Groups by Date.
  • Quick Logs: Displayed alongside standard workouts, identifiable by type.
• 3.5.2 Statistics
  • Visualizes progress over time.
  • Key Metrics: Volume (Weight * Reps), Frequency, Body Weight trends.

3.6. User Interface Logic

• 3.6.1 Navigation
  • Mobile: Bottom navigation bar.
  • Desktop: Side rail navigation.
  • Responsiveness: Main layout container adapts padding/margins based on viewport breakpoint.
• 3.6.2 Input Behavior
  • Search: Exercise selectors must support text search filtering.
  • Auto-Clear: Search inputs should clear/select text on focus for rapid entry.

3.7. Admin Capabilities

Accessible only if User.role === 'ADMIN'.

• User List: View all registered users (showing Block status, First Login status).
• Actions:
  • Toggle Block: Ban/Unban access.
  • Delete User: Permanent removal.
  • Reset Password: Admin can manually trigger password reset flows.

4. Technical Constants & Constraints

• Database: SQLite (via Prisma).
• API Schema: REST-like (JSON).
• Timezones: Dates stored as UTC in DB, displayed in Local Time on client.
• Offline Mode: Currently NOT supported (requires active connection for mutations).