Skip to main content

Workouts

1. Purpose of Workouts​

Workouts have two main purposes.

First, they help users organise their Habits.

If a user has 30, 40, or 50 Habits, one long Habit list becomes tiring to navigate. A Workout solves this by acting like a folder.

Use the computer folder analogy when understanding the model:

A Workout is like a folder for Habits.
It groups Habits together so the user can access related Habits without cluttering the main Habit screen.

Second, Workouts create an important future scope for Challenges.

NEO is a multiplayer habit game. Later, Challenges will need clean scopes:

  • one Habit;
  • one Workout;
  • Open / everything.

A Workout gives us the middle scope:

more flexible than one Habit, but more focused than everything.

This is why Workout architecture needs to be clean from the beginning.

2. Workout vs Playlist​

The primitive for a Workout is the existing Playlist architecture, but Workout is a different formulation.

A Playlist is a user-owned programmed object.

A Workout is different.

A Workout is not a programmed routine.

A Workout is:

a flexible folder/configuration of Habits.

A Workout stores which Habits are included.

A Workout does not store:

  • required order;
  • required reps;
  • required duration;
  • rest periods;
  • set counts;
  • rounds;
  • strict sequence logic.

When the user opens a Workout, they decide in the moment:

  • which Habit to do;
  • how many reps;
  • how long;
  • how many completions;
  • whether to repeat something;
  • when to leave;
  • when to come back.

So the core definition is:

Workout = flexible folder of Habits.

3. Core Workout Definition​

A Workout is a reusable configuration of Habits.

Example:

Workout: Ab Blast
Habits:
- Crunches
- Plank
- Leg Raises

If another user builds a Workout with exactly the same Habit set:

- Leg Raises
- Crunches
- Plank

then it is the same Workout.

It should resolve to the same Workout ID.

The Workout identity is based on the unordered set of Habit IDs.

It is not based on:

  • creator;
  • order;
  • name;
  • visual display order;
  • time created.

4. Workout Identity Rule​

Workout identity should be based on the unordered set of included Habit IDs.

Example:

Pushups
Pullups
Meditation

and:

Meditation
Pushups
Pullups

are the same Workout.

They should resolve to the same Workout ID.

Recommended backend approach:

canonicalHabitIds = sort(habitIds)
workoutKey = hash(canonicalHabitIds)

Then:

  • if workoutKey exists, use the existing Workout key;
  • if workoutKey does not exist, create a new Workout key;
  • this key is shared between all accounts using the same Habit configuration.

This prevents duplicate Workout objects in the backend.

Important:

The Workout key is generated from the sorted Habit IDs. This does not require the Workout to have a fixed order. The UI display order is separate from the identity key.

5. Workout as Shared Configuration​

A Workout is not owned.

A Workout is bookmarked.

If multiple users bookmark the same Habit configuration, they are connected to the same Workout object.

Example:

User A builds:

Pushups + Pullups + Squats

User B later builds:

Squats + Pushups + Pullups

Backend should detect this as the same configuration.

Both users reference the same Workout ID.

This allows:

  • shared friend leaderboards;
  • friend overlap detection;
  • easy bookmarking of friends’ Workouts later;
  • future Workout-scoped Challenges;
  • fewer duplicate backend objects;
  • cleaner data model.

6. Building vs Bookmarking a Workout​

There are two paths into a Workout.

Path 1 — Build Workout​

The user builds a Workout by selecting Habits.

When the user finishes building it:

  • backend generates or finds the matching Workout ID;
  • the Workout becomes bookmarked on the user’s account;
  • user must have a name attached to it.

Building a Workout results in that Workout showing as bookmarked for the user.

Path 2 — Bookmark Existing Workout​

The user discovers an existing Workout and bookmarks it.

This is especially important later when users can view friends’ Workouts.

Example:

  • user finds a friend’s Workout;
  • user bookmarks that Workout;
  • now both users share the same Workout ID;
  • both can appear in the same friend-scoped Workout leaderboard.

This is essential for multiplayer.

7. Workout Naming​

When a user builds a Workout, they must give it a name.

A Workout cannot be built without a name.

However, we can provide defaults:

Workout A
Workout B
Workout C

The name is not the Workout identity.

The same Workout ID can have different user-facing names for different users.

Example:

Same Workout ID:

Pushups + Pullups + Squats

User A calls it:

Morning Strength

User B calls it:

Travel Workout

This is allowed.

The name should be stored on the player’s bookmarked relationship with the Workout, not used to define the global Workout object.

Recommended relationship:

PlayerBookmarkedWorkout
- playerId
- workoutId
- name
- bookmarked
- createdAt
- updatedAt
- lastOpenedAt

The user can rename their Workout later.

Renaming does not change the Workout ID.

8. Same Habit Can Feature in Multiple Workouts for the Same User​

The same Habit can appear in multiple Workouts configured/bookmarked by the same user.

Example:

Pushups can appear in:

Morning Strength
Travel Workout
Chest Day
Full Body

This is expected.

There is no conflict.

A Habit is reusable across Workouts.

The Habit is not duplicated. The Workout references the Habit.

If the daily score for Pushups is +1000 in Travel Workout, it is also +1000 in Chest Day.

If the user then completes Pushups inside Chest Day and the Pushups score becomes +1200, then when the user opens Travel Workout, Pushups will also show +1200.

The Habit has one canonical score/state everywhere it appears.

9. Habit Does Not Need to Be Bookmarked to Be in a Workout​

A Habit can be inside a Workout even if that Habit is not bookmarked as a standalone Habit.

This is central to the model.

Example:

User bookmarks:

Workout: Ab Blast

Inside Ab Blast:

Crunches
Plank
Leg Raises

The user has not bookmarked those Habits individually.

Result:

  • Ab Blast appears in the user’s Workouts area;
  • Crunches, Plank, and Leg Raises are accessible inside Ab Blast;
  • Crunches, Plank, and Leg Raises do not necessarily appear on the main bookmarked Habits page;
  • if the user wants Plank to appear on the main Habits page, they must bookmark Plank separately.

This is the point of Workouts:

Workouts let users organise and access Habits without cluttering the main Habits screen.

A Habit can exist:

  • only inside a Workout;
  • only as a standalone bookmarked Habit;
  • both inside one or more Workouts and as a standalone bookmarked Habit.

10. A Habit Can Be Bookmarked and Also Exist Inside Workouts​

A Habit can be bookmarked as a standalone Habit and also appear inside one or more Workouts.

This is expected and valid.

Example:

The user wants Pushups visible on the main Habits page because they do it often.

The user also has Workouts such as:

Chest Day
Travel Workout
Full Body Strength

and each of those Workouts includes Pushups.

This is totally acceptable.

Result:

  • Pushups appears on the main bookmarked Habits page;
  • Pushups also appears inside each Workout that includes it;
  • Pushups has the same score and state everywhere;
  • completing Pushups in any context updates the same canonical Pushups score.

This means bookmarked Habit visibility and Workout inclusion are separate concepts.

11. Configuring / Rebuilding a Workout​

A Workout is not edited in the old owned-object sense.

If a user changes the Habit set, they move to a different Workout configuration.

Example:

Current Workout:

Pushups
Pullups
Squats

User adds:

Meditation

New configuration:

Pushups
Pullups
Squats
Meditation

This is now a different Workout.

Therefore:

  • new Workout ID;
  • new Workout leaderboard context;
  • new friend overlap context;
  • old Workout still exists for other users, but no longer for the user who changed it;
  • user’s bookmarked Workout relationship now points to the new Workout configuration.

The user-facing wording should be:

Rebuild Workout

Important:

If the user changes the Workout configuration, the name remains the same until the user changes it.

Example:

User has:

Morning Strength
= Pushups + Pullups + Squats

They add Meditation.

Now:

Morning Strength
= Pushups + Pullups + Squats + Meditation

The name can remain Morning Strength, even though the underlying Workout ID changed.

12. Workout Build Mode​

If the user builds a new Workout or rebuilds an existing Workout, they enter Workout Build Mode.

This is separate from the current Playlist builder.

Workout Build Mode is a new, simpler interface.

It will be provided in a separate visual brief.

Core behaviour:

  • user selects Habits to include;
  • no reps/time/rest periods are configured;
  • no fixed order is configured;
  • when saved, backend generates/finds the canonical Workout ID;
  • the Workout becomes bookmarked on the user’s account.

Workout Build Mode should be simple and fast to build.

13. Front-End Workout Interface​

Workouts will exist in their own list/view alongside the main Habits tab.

The user should be able to tap a Workout button to enter the Workouts view.

In Workouts view, the user sees a list of Workouts.

This Workouts view should support the same broad bookmark/all-view logic as Habits:

  • Bookmarked Workouts view = the user’s bookmarked Workouts;
  • All Workouts view = broader Workout discovery/selection view.

The exact front-end design will be provided separately, but the model should support this structure.

14. Discovering Friends’ Workouts from Workouts View​

In the Workouts All View, the user should eventually be able to see Workouts bookmarked by friends.

This gives users an easy way into multiplayer.

The user can:

  • enter Workouts view;
  • switch to All View;
  • see Workouts their friends have bookmarked;
  • bookmark one of those Workouts;
  • immediately share the same Workout ID;
  • appear on that Workout’s friend-scoped leaderboard.

This is similar to the Habits All View, where the user can browse beyond only their bookmarked items.

This makes Workout discovery simple and social.

15. Side-Scrolling Workout Execution Interface​

Use the same side-scrolling interface style that currently exists for Playlists.

The team already understands this interface.

When a user opens a Workout, they enter a horizontal side-scrolling view of the Habits inside that Workout.

The card is similar to the existing Habit completion card, but resized/narrower as needed to fit the Workout context.

Each Habit inside the Workout should retain the same core functionality:

  • display current Habit state;
  • display current score;
  • allow completion;
  • use the normal Habit completion flow;
  • reflect whether that Habit is completed/positive or uncompleted/negative;
  • allow the usual Habit interactions where appropriate.

16. Workout Display Order​

Workout identity ignores order.

However, the side-scrolling UI still needs a display order.

Default display order:

highest-level Habit furthest left, lowest-level Habit furthest right.

Use Habit level / total score as the basis.

Meaning:

  • leftmost = strongest/highest-level Habit;
  • rightmost = weakest/lowest-level Habit.

This gives the Workout a useful personal order while avoiding extra setup decisions for the user. The user does not need to manually arrange Habits when building the Workout. The order is generated intelligently from their own progress, without making order part of the Workout identity.

The same Workout can display in a different order for different users because each user has different levels in the included Habits.

That is acceptable.

17. When to Reorder Workout Cards​

A Habit inside the Workout may overtake another Habit in level/total score during the session.

Do not reorder live while the Workout is open.

Example:

Before opening:

Pullups level 10
Pushups level 9

User completes Pushups enough to reach level 11.

Do not move Pushups live while the Workout is open.

Instead:

  • calculate order upon opening the Workout;
  • keep that order stable while open;
  • recalculate order next time the Workout is opened and a request is sent to the backend.

This will be easier to build, and reordering while using the Workout will probably be confusing.

18. Workout Execution Behaviour​

A Workout is always available to open.

A Workout has no state of completion.

It can be done indefinitely.

The user can open a Workout multiple times per day.

The user can leave and return later.

The user can perform any Habit inside the Workout:

  • once;
  • multiple times;
  • many times;
  • at any time of day;
  • in any order.

Example session:

Open Workout
Do Pushups
Do Pushups again
Do Pullups
Close Workout
Come back later
Do Squats
Do Pushups again
Close Workout

All completions count through the normal Habit scoring system.

19. Habit State Is Shared Everywhere​

A Habit has the same score and state everywhere it appears.

If Pushups appears:

  • on the main Habits page;
  • inside Workout A;
  • inside Workout B;
  • inside a future Challenge;

then it is still the same Pushups score/state.

The Workout does not own a separate version of the Habit score.

The Workout simply represents the Habit inside that container.

Therefore:

  • the score shown for Pushups is the same everywhere;
  • the completed/positive or uncompleted/negative state is the same everywhere:
    • if completed/positive, inherit the white design;
    • if uncompleted/negative, inherit the black design.

Example:

If Pushups is positive today on the main Habits page, Pushups should also appear positive inside any Workout containing Pushups.

If Pushups is negative today, it should appear negative everywhere.

20. Workout Score​

A Workout has its own cumulative score.

The Workout score is based on the sum of the current scores of the Habits inside that Workout.

Example:

Workout:

Pushups: +500
Pullups: -100
Squats: +300

Workout score:

+700

The Workout does not create a separate score economy.

It aggregates the scores of its included Habits.

As the user completes Habits inside or outside the Workout, the underlying Habit score changes. The Workout score reflects those included Habit scores.

Important:

The Habit score is canonical. The Workout score is derived.

21. Habits Inside Workouts Still Contribute to Overall Score​

Habits inside a Workout contribute to the user’s overall Habit score whether or not those Habits are bookmarked individually.

Example:

User has not bookmarked Pullups as a standalone Habit.

But Pullups exists inside a bookmarked Workout.

If the user completes Pullups inside that Workout:

  • Pullups gains score;
  • Pullups contributes to the user’s overall score;
  • Pullups now has active Habit score state;
  • Pullups may still not appear on the main bookmarked Habits page unless separately bookmarked.

This is important:

Workout inclusion does not isolate the Habit from the main scoring economy.

The Habit score contributes globally to the player’s Habit/Dojo score.

22. Workout Rest Timer​

When the user completes a Habit inside a Workout, start/reset a simple elapsed timer.

This timer means:

time since the last completion inside this Workout.

It is not a programmed rest period.

It is just a lightweight rest timer.

The timer stops when the user closes the Workout.

Do not store rest periods in the Workout model.

22.1 Rep-Based Habits​

For rep-based Habits:

  • user completes the Habit;
  • Workout rest timer starts/resets immediately;
  • timer shows elapsed time since that completion;
  • user chooses when to continue;
  • user completes the Habit again;
  • timer restarts to zero.

Example:

  • user completes Bench Press;
  • timer starts at 0;
  • user sees 45 seconds, 90 seconds, 2 minutes, etc.;
  • user chooses when to continue;
  • user completes Bench Press again;
  • timer restarts to zero.

22.2 Time-Based Habits​

For time-based Habits:

  • while the timed Habit is running, the Habit’s own timer takes priority;
  • Workout rest timer is hidden while the timed Habit is active;
  • once the timed Habit is complete, the Workout rest timer starts/resets;
  • timer then shows elapsed time since the end of that timed activity.

This applies whether the timed activity ended manually or because the timer elapsed.

23. No Required Reps / Sets / Time in Workout​

The Workout does not store prescribed reps, sets, or durations.

When the user opens a Habit inside the Workout, the normal Habit completion UI handles dose selection.

Example:

Workout contains:

Pushups
Pullups
Plank

When user opens Pushups, they choose:

10 reps
20 reps
30 reps

or whatever the Habit’s normal completion UI supports.

The Workout does not define this in advance.

24. Workout Leaderboards​

Each Workout configuration has its own leaderboard.

Workout leaderboards are friend-scoped.

There will not be a public leaderboard for Workouts.

Only friends leaderboards.

The friend-based social value is:

“Which of my friends also have this Workout bookmarked, and how am I doing compared to them?”

A Workout leaderboard should show friends who have the same Workout ID bookmarked.

Example:

Workout ID abc123:

Pushups + Pullups + Squats

Friends using this same Workout ID can appear in the Workout leaderboard.

If I rebuild the Workout by adding Meditation:

Pushups + Pullups + Squats + Meditation

then I am now using a new Workout ID.

The previous leaderboard no longer applies to me.

If a friend also has the new Workout ID bookmarked, they appear with me in the new Workout leaderboard.

25. Global Workout Bookmark Count​

Although Workout leaderboards are friend-scoped, we may later show global popularity signals.

The main global signal should be:

global bookmark count.

Example:

14,820 people have bookmarked this Workout

This is discovery and social proof, not global competition.

There will not be a public leaderboard for Workouts.

Global bookmark count may later support global Workout discovery, such as:

most bookmarked Workouts in the world.

26. Discovering Friends’ Workouts​

There are two future discovery surfaces for friends’ Workouts.

26.1 Workouts All View​

In the Workouts All View, the user should eventually be able to see Workouts bookmarked by friends.

This gives users a fast way into shared multiplayer contexts.

Example flow:

  • user enters Workouts view;
  • user switches from Bookmarked View to All View;
  • user sees Workouts bookmarked by friends;
  • user bookmarks one of those Workouts;
  • now both users share the same Workout ID;
  • both can appear in the same friend-scoped Workout leaderboard.

This should be considered the main discovery path.

26.2 Friend Habit Profile​

Later, a user should eventually be able to view a friend’s Workouts from that friend’s habit profile.

This will not be version 1 of Workouts, but we should design the backend so it is possible later.

Example flow:

  • user opens friend’s habit profile;
  • sees friend’s bookmarked Workouts;
  • taps a Workout;
  • bookmarks that Workout;
  • now both users share the same Workout ID;
  • both can appear in the same friend-scoped Workout leaderboard.

This is one of the main reasons Workout identity must be configuration-based instead of user-owned.

27. Workouts and Challenges​

The final feature of Habits that we will build is Challenges.

We do not need to build them now or get into the full details in this brief, but later Challenges will be based on a scope.

Possible Challenge scopes:

One Habit​

Example:

Who can do the most Pushups this week?

One Workout​

Example:

Who can earn the most Power in this Workout over the challenge period?

Open / Everything​

Example:

Who can earn the most total Power this week?

Workout scope is important because it gives users a middle ground:

  • more flexible than one Habit;
  • more focused than Open/everything.

This is why Workout architecture needs to be clean.

A Workout should be a stable shared object so that Challenges can easily reference it.

28. Data Model Recommendation​

Core Workout object:

Workout
- id
- canonicalKey
- habitIdsCanonical[]
- createdAt
- updatedAt

canonicalKey is generated from sorted Habit IDs.

Relationship:

PlayerBookmarkedWorkout
- playerId
- workoutId
- name
- bookmarked
- createdAt
- updatedAt
- lastOpenedAt

Notes:

  • name is user-specific;
  • bookmarked controls visibility;
  • lastOpenedAt may be useful for sorting or resuming;
  • createdAt and updatedAt are useful metadata and should be included.

29. What There Is No Need to Build Into Workout​

There is no need to build these into the base Workout object:

  • fixed execution order;
  • required reps;
  • required duration;
  • rest periods;
  • sets;
  • rounds;
  • forced completion;
  • fixed sequence logic;
  • playlist-style programming.

These belong to future Playlist functionality.

30. Summary of Key Rules​

  1. Workout is a different formulation from Playlist.
  2. Workout is a flexible folder/configuration of Habits.
  3. Workout identity is based on the unordered set of Habit IDs.
  4. Same Habit configuration = same Workout ID.
  5. Workout key is shared between all accounts with the same configuration.
  6. Workout name is user-specific and does not define identity.
  7. A user must name a Workout, but defaults can be Workout A, Workout B, Workout C.
  8. Workouts are bookmarked, not owned.
  9. Building a Workout results in that Workout becoming bookmarked on the user’s account.
  10. Users can later bookmark a friend’s Workout.
  11. Same Habit can appear in multiple Workouts configured by the same user.
  12. Habit does not need to be bookmarked to be inside a Workout.
  13. A Habit can be bookmarked as standalone and also exist inside one or more Workouts.
  14. Bookmarking a Workout does not bookmark the Habits inside it.
  15. Rebuilding a Workout changes the underlying Workout ID if the Habit set changes.
  16. If configuration changes, the old Workout still exists for other users but no longer for the user who changed it.
  17. Workouts have their own list/view alongside the main Habits tab.
  18. Workouts All View can later surface friends’ bookmarked Workouts.
  19. Workout uses the same side-scrolling interface style as current Playlists.
  20. Workout display order is based on user’s Habit level/total score.
  21. Highest-level Habit appears furthest left.
  22. Lowest-level Habit appears furthest right.
  23. Do not reorder live while Workout is open.
  24. Recalculate order when the Workout is opened.
  25. A Workout is always available to open.
  26. A Workout has no state of completion.
  27. User can open a Workout multiple times per day.
  28. User can perform any Habit inside the Workout any number of times.
  29. Habit score/state is shared everywhere that Habit appears.
  30. Workout score is derived from included Habit scores.
  31. Habits inside Workouts still contribute to overall score, even if not bookmarked individually.
  32. Workout rest timer shows elapsed time since last completion inside the Workout.
  33. For rep-based Habits, rest timer starts immediately after completion and resets if the Habit is completed again.
  34. For time-based Habits, rest timer is hidden while Habit timer runs, then starts after the timed activity ends.
  35. Timer stops when Workout closes.
  36. Workout leaderboards are friend-scoped.
  37. There will not be a public leaderboard for Workouts.
  38. Global bookmark count/discovery may come later.
  39. Workouts are important because they organise large Habit sets and give future Challenges a clean middle scope between one Habit and Open/everything.

31. Later Playlist Architecture​

Do not discard the current Playlist architecture.

This is a later feature and we do not need to focus on it now, but the work already done is useful.

The Playlist work, including front-end work, is still valuable.

Later, a Playlist can become a user-owned programmed object that stems from the Habits inside a Workout.

Future model:

Workout = flexible folder/configuration of Habits.
Playlist = user-owned programmed sequence built from a Workout.

A Playlist may later support:

  • fixed order;
  • rest periods;
  • timed progression;
  • automatic progression;
  • manual mode;
  • audio cues;
  • structured guided routines.

For now, the team should preserve the Playlist architecture but focus implementation on the new Workout model.