Living documentation — last reviewed 2026-05-28

Exercises — code map

API

Controllers

File	Base path	Notes
`apps/api/src/exercises/exercises.controller.ts`	`/organizations/:orgId/exercises`	Standard CRUD + library + overrides
`apps/api/src/exercises/exercise-search.controller.ts`	`/exercises`	`GET /search` — hybrid search, optional `?orgId`
`apps/api/src/exercises/admin-canonical.controller.ts`	`/admin/exercises/canonical`	Platform-admin: seed, enrich, jobs

Services

File	Responsibility
`apps/api/src/exercises/exercises.service.ts`	CRUD, library list, single-read
`apps/api/src/exercises/exercise-overrides.service.ts`	Upsert/reset overrides; exports `mergeExerciseWithOverride`
`apps/api/src/exercises/exercise-search.service.ts`	RRF lexical + trgm + semantic search
`apps/api/src/exercises/canonical-seed.service.ts`	R2 JSON → canonical upsert + Voyage embed
`apps/api/src/exercises/canonical-seed.processor.ts`	BullMQ processor for seed jobs
`apps/api/src/exercises/canonical-enrich.service.ts`	Anthropic Haiku Hebrew/Russian alias enrichment
`apps/api/src/exercises/canonical-enrich.processor.ts`	BullMQ processor for enrichment jobs
`apps/api/src/exercises/canonical-utils.ts`	Slug / equipment / muscle normalization helpers

DTOs (`apps/api/src/exercises/dto/`)

create-exercise.dto.ts, update-exercise.dto.ts, upsert-exercise.dto.ts
canonical-seed.dto.ts, canonical-enrich.dto.ts

Routes

Route	Method
`GET /organizations/:orgId/exercises`	`findAll` (legacy org-only list)
`GET /organizations/:orgId/exercises/library`	`findAllForLibrary` (merged + paginated)
`GET /organizations/:orgId/exercises/library/:id`	`findByIdForLibrary`
`GET /organizations/:orgId/exercises/:id`	`findById` (accepts canonical)
`POST /organizations/:orgId/exercises`	`create` org-custom
`PATCH /organizations/:orgId/exercises/:id`	`update` org-custom
`DELETE /organizations/:orgId/exercises/:id`	`remove` org-custom (soft)
`POST /organizations/:orgId/exercises/upsert`	`upsert` by case-insensitive name
`PUT /organizations/:orgId/exercises/:id/override`	`upsertOverride`
`DELETE /organizations/:orgId/exercises/:id/override`	`deleteOverride` (reset)
`GET /exercises/search`	Hybrid search; `?orgId` optional
`POST /admin/exercises/canonical/seed`	Platform admin
`POST /admin/exercises/canonical/enrich`	Platform admin
`GET /admin/exercises/canonical/jobs`	Platform admin
`GET /admin/exercises/canonical/jobs/:queue/:id`	Platform admin

Web

Components

apps/web/src/components/overview/workouts/exercise-library-browser.tsx — coach library tab
apps/web/src/components/overview/workouts/exercise-autocomplete.tsx — in-builder picker
apps/web/src/components/overview/workouts/exercise-video-dialog.tsx — preview demo
TODO: verify — likely a dedicated movement library detail/edit page.

E2E

apps/web/e2e/specs/coach-movements-library.spec.ts — library browse + override flow.

DB

libs/db/src/lib/schema/workouts.ts (same file as workouts):

exercises — both canonical (org_id null) and org rows.
exercise_org_overrides — JSONB diff per (org, exercise).
exercise_comments — comments on a workout_movement (lives in comments.ts).

Indexes (exercises):

Index	Columns / clause
`exercises_slug_unique_idx`	UNIQUE on `slug` WHERE `slug IS NOT NULL AND organization_id IS NULL`
`exercises_search_tsv_idx`	GIN on `search_tsv`
`exercises_name_trgm_idx`	GIN on `name gin_trgm_ops` (pg_trgm, migration 0039)
`exercises_embedding_idx`	HNSW on `embedding` (`vector_cosine_ops`)
`exercises_movement_pattern_idx`	partial on `movement_pattern` WHERE not null
`exercises_org_id_idx`	on `organization_id`
`exercises_forked_from_id_idx`	partial WHERE not null

Indexes (exercise_org_overrides):

exercise_org_overrides_org_exercise_unique UNIQUE on (organization_id, exercise_id)
exercise_org_overrides_org_idx on organization_id

Shared

libs/shared/src/lib/schemas/exercise.schema.ts — Zod schemas for read responses, category/kind enum values.
libs/shared/src/lib/exercise-overrides.ts — overridableExerciseFieldKeys (the allowlist), OverridableExerciseFields type, EffectiveExercise type, MovementSourceFilter enum. TODO: verify exact filename.
libs/shared/src/lib/agent-schemas/read.ts — agent-facing exercise search query schema (exerciseSearchQuerySchema).

Tests

File	Type
`apps/api/src/exercises/exercise-overrides.service.unit.spec.ts`	Unit — merge logic, override upsert
`apps/api/src/exercises/exercise-search.int.spec.ts`	Integration — RRF, lexical/semantic/hybrid modes
`apps/web/e2e/specs/coach-movements-library.spec.ts`	E2E — library browse + override

Exercises — behavior spec Exercises — data model