Skip to main content

Lift Assist & Progression Guidance

The Lift Assist feature is designed to provide users with automated, set-by-set progression guidance for exercises. It aims to help you consistently apply progressive overload by analyzing your performance (weight, reps, RPE) relative to your active training goals, and suggesting adjustments for your next session.

Overview for Everyone​

Lift Assist helps you answer the question: "What should I lift next time?"

  • Automated Suggestions: After you complete and log a workout, Lift Assist analyzes each working set.
  • Personalized Guidance: It considers your current training program's goals (e.g., target rep ranges, RPE).
  • Set-by-Set Advice: For each set of an exercise, it might suggest:
    • Increasing the weight.
    • Increasing the number of reps.
    • Maintaining the current weight and reps.
    • Decreasing the weight (if a set was too difficult).
  • Informed Training: These suggestions are then available when you next perform that exercise, helping you make informed decisions to drive progress.

Why This Feature Matters (User Benefits)​

  • 📈 Smarter Progression: Takes the guesswork out of progressive overload.
  • 💪 Consistent Gains: Helps ensure you're challenging yourself appropriately to keep making progress.
  • 🎯 Stay on Target: Aligns your efforts with the specific goals of your training program (e.g., strength, hypertrophy).
  • 🧠 Learn Your Limits: By tracking RPE and seeing the system's response, you gain a better understanding of your effort levels.
  • 💡 Motivation: Clear guidance can be motivating and help you push for improvements.

Core Concepts​

  • ProgressionSuggestion: This is the actual piece of advice stored by the system. For each exercise and each set number, Lift Assist stores a suggestion (e.g., "For set 1 of Bench Press, aim for 60kg for 8 reps").
  • TrainingFocusProfile: This defines the "rules" or targets for your current training. It comes from your active ProgramPlan or a specific ProgramUserInstance override. It includes:
    • Target rep ranges (e.g., 6-10 reps).
    • Target RPE (Rate of Perceived Exertion).
  • Completed Set Analysis: The process where Lift Assist looks at the ExerciseSet data you logged in your WorkoutHistoryEntry (weight, reps, RPE) and compares it against your TrainingFocusProfile.
  • RPE (Rate of Perceived Exertion): A subjective measure of how difficult a set felt, typically on a scale of 1-10. This is a crucial input for Lift Assist to make good suggestions.

Key Workflows​

This is how suggestions are generated:

  1. Workout Completion: You log a workout, including exercises, sets (weight, reps, RPE), and mark it as complete.
  2. Trigger: The system automatically triggers the Lift Assist calculation process for that WorkoutHistoryEntry.
  3. Profile Retrieval: Lift Assist determines your current TrainingFocusProfile:
    • First, it checks if your active ProgramUserInstance has a specific trainingFocusOverride.
    • If not, it uses the default trainingFocus from the ProgramPlan of your active ProgramUserInstance.
    • If no active program, it might (if enabled) use the trainingFocus from the ProgramWorkoutTemplate used in the just-completed workout.
    • If no profile is found, suggestions are not calculated for that workout.
  4. Set Analysis: For each valid working set (logged weight > 0, reps > 0) in the completed workout:
    • It compares your performed reps and RPE against the minReps, maxReps, and rpeTarget from your profile.
    • Based on rules (see "Progression Logic Details" below), it determines whether to suggest increasing weight, increasing reps, maintaining, or decreasing weight.
    • It also suggests a target RPE for the next attempt.
  5. Save Suggestions: The generated ProgressionSuggestion (including target weight, reps, RPE, and a message) is saved (or updated if one already exists) for that userId, exerciseId, and targetSetNumber.
  6. Cleanup: Suggestions for set numbers higher than what you performed in this session are deleted (e.g., if you did 3 sets, but a suggestion for set 4 existed, it's removed).

This is primarily handled by the POST /api/lift-assist/calculate endpoint, typically called internally after a workout is saved.

Progression Logic Details​

The core logic within calculateAndSaveSuggestions in lift-assist.service.ts determines the next steps. Here's a simplified overview (based on a profile with minReps, maxReps, targetRpeMin, targetRpeMax):

  • If RPE was too low (e.g., < targetRpeMin):
    • Suggest: INCREASE_REPS, maintain weight.
    • Message: "Last RPE low. Aim for more reps."
  • If RPE was on target (e.g., targetRpeMin <= RPE <= targetRpeMax):
    • And reps < maxReps:
      • Suggest: INCREASE_REPS, maintain weight.
      • Message: "Good set! Aim for more reps."
    • And reps >= maxReps:
      • Suggest: INCREASE_WEIGHT (by a small increment), DECREASE_REPS (to minReps).
      • Message: "Max reps hit! Increase weight. Aim for [minReps] reps."
  • If RPE was too high (e.g., RPE > targetRpeMax):
    • And RPE was very high (e.g., 10) with low reps:
      • Suggest: DECREASE_WEIGHT, maintain reps (or aim for minReps).
      • Message: "Last RPE maxed. Reduce weight."
    • Else (RPE high but manageable):
      • Suggest: MAINTAIN weight and reps.
      • Message: "Last RPE high. Focus on matching reps cleanly."
  • If RPE was not logged:
    • Suggest: MAINTAIN weight and reps.
    • Message: "Log RPE on sets for better guidance."

The system also calculates target weight and reps for the suggestion based on these rules and configured increments (e.g., SMALLEST_WEIGHT_INCREMENT_KG).

Technical Deep Dive (For Developers)​

This section outlines key technical components for those working with the codebase.

Primary Data Models​

Refer to schema.prisma for full definitions.

  • WorkoutExerciseProgressionSuggestion: The central model. Stores one suggestion per userId, exerciseId, and targetSetNumber. Contains:
    • suggestedWeight, suggestedReps, suggestedRpe
    • weightChange, repsChange (enums: INCREASE, DECREASE, MAINTAIN)
    • message (textual advice)
    • Context from the set that triggered the suggestion (sourceHistorySetId, sourceWeight, sourceReps, sourceRpe, lastSessionDate)
  • User: The authenticated user.
  • Exercise: The master exercise record.
  • WorkoutHistoryEntry: The log of a completed workout. Input for suggestion calculation.
  • ExerciseSet: Details of each performed set (weight, reps, RPE) within a WorkoutHistoryEntry. Crucial input.
  • ProgramTrainingFocus: Defines target rep/set/RPE ranges used by the logic. Linked via ProgramPlan or ProgramUserInstance.
  • ProgramUserInstance: User's enrollment in a ProgramPlan, can have trainingFocusOverride.
  • ProgramPlan: The structured training plan, has a default trainingFocus.
  • ProgramWorkoutTemplate: Can have a fallback trainingFocus if no active program.

Key API Endpoints​

Endpoints are defined in src/modules/lift-assist/lift-assist.route.ts and prefixed with /api/lift-assist. Authentication is required.

MethodEndpointController FunctionDescription
POST/calculate?workoutHistoryId={id}handleCalculateSuggestionsTriggers suggestion calculation based on a completed WorkoutHistoryEntry ID.
GET/suggestions?exerciseId={id}handleGetSuggestionsRetrieves stored suggestions for the authenticated user and a specific Exercise ID.
DELETE/suggestionshandleClearSuggestionsClears all stored progression suggestions for the authenticated user.

Code Structure & Helpers​

  • Service (lift-assist.service.ts):
    • calculateAndSaveSuggestions(userId, completedWorkoutHistoryId): Core engine for generating and saving suggestions.
    • getSuggestionsForExercise(userId, exerciseId): Retrieves suggestions.
    • clearSuggestions(userId): Deletes user's suggestions.
    • _getApplicableTrainingProfile(...): Determines which ProgramTrainingFocus to use based on active program, overrides, or template fallback.
  • Controller (lift-assist.controller.ts): Handles HTTP requests, calls service methods, and formats responses.
  • Schemas (lift-assist.schema.ts): Uses @sinclair/typebox to define request/response schemas for validation and typing (e.g., GetSuggestionsQuerySchema, ProgressionSuggestionDataSchema).
  • Constants: Defined in lift-assist.service.ts (e.g., SMALLEST_WEIGHT_INCREMENT_KG, WEIGHT_DECREMENT_FACTOR).

Important Technical Considerations​

  • Progression Logic: The rules are implemented in calculateAndSaveSuggestions. It's crucial that this logic is clear and maintainable.
  • Training Profile Hierarchy: The _getApplicableTrainingProfile method correctly prioritizes user overrides, then program defaults, then template fallbacks (if enabled).
  • Upsert Strategy: Suggestions are saved using prisma.workoutExerciseProgressionSuggestion.upsert to ensure that for any given user, exercise, and set number, there's only one active suggestion, which gets updated with the latest calculation.
  • Data Integrity: Suggestions for set numbers not performed in the most recent session for an exercise are cleared to avoid stale advice.
  • Error Handling & Logging: The controller includes error handling and logging for robust operation.
  • Performance: Fetching the TrainingFocusProfile and WorkoutHistoryEntry with its sets should be efficient. Indexes are in place for WorkoutExerciseProgressionSuggestion.

Future Enhancements (Potential)​

  • More sophisticated progression algorithms (e.g., considering e1RM, velocity-based training inputs).
  • User customization of progression rules or aggressiveness.
  • Visualizations of suggested vs. actual progression over time.
  • "What-if" scenarios for different RPE inputs.

This documentation provides a comprehensive guide to the Lift Assist feature. For precise data model definitions, refer to schema.prisma and for implementation details, consult the relevant files in the src/modules/lift-assist/ directory.