Building the Foundation: Movement Library Data Model & Video Reference Schema

v1.0.69 — Released 2025

Every great fitness platform is only as good as its understanding of movement. With v1.0.69, we're shipping the canonical Movement Registry — the data model that everything else in the platform will rely on when it needs to know what a movement is, how it should be coached, who can safely perform it, and what it looks like on video.

Why a Movement Registry?

Without a shared, structured registry, movement data gets scattered. Session authors duplicate coaching cues. Scaling logic is hard-coded per workout. Injury restriction engines have no clean way to reason about substitutions. Video assets float without a home.

The Movement Registry solves all of this by making every movement a first-class record — one that can be referenced, updated, and reasoned about consistently across the entire platform.

What's in a Movement Record?

Each movement in the registry carries five key pieces of structured data:

Coaching Cues The instructional language that goes with the movement — the same cues a great coach would give, stored once and surfaced everywhere the movement appears, from session delivery to video annotation.

Fault Descriptors Common errors and breakdown patterns. These give coaches a structured vocabulary for feedback and lay the groundwork for AI-assisted movement quality analysis in future releases.

Scaling Alternatives A tiered list of substitute movements. When the platform generates a session for an athlete who needs to scale, it has a clean, explicit path to follow rather than guessing.

Mobility Prep Links Warm-up and mobility work that's relevant to the movement. Coaches can lean on these to auto-populate session preambles with targeted prep, rather than starting from scratch every time.

Mux Video Asset Reference Each movement can be linked to a demonstration video hosted on Mux, giving members clear visual references and giving coaches a canvas for frame-level annotation.

A Foundation, Not a Ceiling

This release is deliberately focused on the data model. There's no new UI in v1.0.69 — what we're doing here is laying the infrastructure that upcoming features depend on:

AI-personalised programming needs to know which movements are equivalent, which are harder, and which are contraindicated for a given athlete.
The coach movement library browser needs a queryable, richly-attributed registry to search and filter.
The injury risk restriction engine needs scaling alternatives and mobility prep links to suggest safe paths forward for athletes with active restrictions.
Video coaching and annotation needs the Mux reference schema to connect playback to the right movement context.

By getting the data model right now, we ensure all of those features are built on a consistent, shared foundation rather than a patchwork of per-feature data stores.

What's Next

With the Movement Registry in place, the next steps are:

Coach-facing movement library UI — browse, search, create, and edit movement records directly from the platform.
Session editor integration — assign movements from the registry when building sessions, with coaching cues and scaling options pre-populated.
Injury restriction engine — use scaling alternatives and mobility prep links to power safe session modification for restricted athletes.
Video upload and association flow — upload movement demonstration videos and link them to registry records via the Mux integration.

The work done in this release makes all of the above significantly cleaner to build. Stay tuned.