Workouts — code map

API (NestJS)

Base path: /organizations/:orgId

Module: apps/api/src/workouts/workouts.module.ts registers the BullMQ workouts-enrichment queue, plus dependencies on MembershipsModule, UsersModule, UploadsModule, R2Module, PushNotificationsModule, and WorkoutAssignmentsModule (for forkSnapshotIfNeeded). It provides and exports WorkoutsService and SectionFidelityService.

DTOs

• apps/api/src/workouts/dto/create-workout.dto.ts — CreateWorkoutDto
• apps/api/src/workouts/dto/update-workout.dto.ts — UpdateWorkoutDto
• apps/api/src/workouts/dto/set-sections.dto.ts — SetSectionsDto, SectionDto (incl. part, validated by sectionPartSchema in the service), MovementDto
• apps/api/src/workouts/dto/update-movement-prescription.dto.ts — UpdateMovementPrescriptionDto (field-for-field whitelist of PrescriptionSchema, incl. calories/bySex, percent_reference + reference, height, levels, group_load)
• apps/api/src/workouts/dto/create-exercise-comment.dto.ts — CreateExerciseCommentDto

Key service methods (apps/api/src/workouts/workouts.service.ts)

• resolveEditTarget(workoutId, assignmentId?) — delegates to WorkoutAssignmentsService.forkSnapshotIfNeeded; returns the snapshot id when assignmentId is supplied.
• requireWorkoutBuilder(orgId) — tier gate for structured-mode writes.
• mapMovementToSnapshot / resolveSnapshotMovement — locate the snapshot’s mirror of a library movement after fork.
• validateStructuredSections — every section write: sectionInputSchema, then the part invariant (findSectionPartIssues → 400 invalid_section_parts), the group-load rule (findGroupLoadIssues → 400 invalid_prescription), shape config and progression bounds.
• insertSections — the one section/movement insert (create and replaceSections): normalized sourceMarks, validated scores, validated part.
• toDetailResponse — coach GET /workouts/:id section mapper (incl. part); member reads use toWorkoutSectionResponse in apps/api/src/common/workout-section.ts.
• deepCopyWorkout — lives in WorkoutAssignmentsService.deepCopyWorkout (apps/api/src/workout-assignments/workout-assignments.service.ts). Copies sections (incl. source_text/source_marks/scores/part), movements, and comments. Program-release staleness compares the same columns in ProgramSessionsService.contentOf.
• WorkoutsService.computeDisplayName (static) — title or first line of description, ≤60 chars.

Section fidelity (apps/api/src/workouts/section-fidelity.service.ts)

• SectionFidelityService.fill(orgId, sections, { scoring }) — loads every name of the sections’ exercises (name, aliases, the org’s override name/aliases) and runs fillSectionFidelity.
• fillSectionFidelity (pure) — fills omitted scores (deriveSectionScoreSlots, apps/api/src/ai/parse/derive-score-slots.ts), omitted sourceMarks (anchorMovementMarks) and omitted workout scoring (deriveScoring); returns FidelityWarning[] (missing_prescription, percent_base_mismatch, text_only_section, invented_score_slot). Called by the MCP upsert and the parse tool.

Web (Next.js)

Key components

• apps/web/src/components/overview/workouts/workout-list-view.tsx — coach library list
• apps/web/src/components/overview/workouts/workout-card.tsx — list item
• apps/web/src/components/overview/workouts/workout-builder.tsx — top-level builder shell
• apps/web/src/components/overview/workouts/workout-builder/ — builder internals:
  • use-builder-state.ts — central state machine (draft sections, movements, undo/redo); updatePart(sectionKey, change) applies a part edit across every block of the part (applyPartChange), and a section reorder re-normalizes parts
  • use-builder-save.ts — POST/PUT orchestration
  • section-payload.ts, prescription-codec.ts, superset.ts — re-export shims; the implementation lives in libs/shared/src/lib/workout-builder/ because the API’s parse eval and unit specs run the same serializer, and an app may not import another app’s source
  • shape.ts — section shape (linear/amrap/emom/…) registry helpers
  • volume.ts — total-volume computation for the right-rail summary
  • keys.ts — stable React keys across reorders; nextPartKey() for a new part
  • components/section-editor.tsx, part-fieldset.tsx (a block’s part: start a new part here / same part as the previous block / leave; part title, class-clock window, note, optional — every edit goes through updatePart), prescription-panel.tsx (calories as a rep kind with an optional ♀/♂ split; percent-of-reference loads, height, levels and group loads pass through unedited), builder-right-rail.tsx, builder-header.tsx, builder-action-bar.tsx, ribbon-action.tsx, shape-renderers.tsx (EMOM interval window max), sortable-section.tsx, section-type-combobox.tsx, num-input.tsx, movement-demo-dialog.tsx, member-preview-panel.tsx (the live “what members see” board in the right rail, structured mode only)
• apps/web/src/components/overview/workouts/workout-builder/components/builder-text-editor.tsx — the freeform (text-only) editor: title, dir="auto" text, scoring, time cap, and the optional “Convert to structured workout” card. Rendered by the builder’s freeform mode and by the schedule sheets’ quick-create (apps/web/src/components/overview/schedule/quick-create-workout-dialog.tsx, a height-bounded scrolling dialog whose untitled placeholder is the name the API saves: dailyWorkoutTitle(session day, class type))
• apps/web/src/components/overview/workouts/paste-workout/ — AI paste-to-structure flow; documented in workout-parse
• apps/web/src/components/overview/workouts/workout-execution-view.tsx — read-only display for non-edit contexts; renders the workout through VerbatimWorkout
• apps/web/src/components/overview/workouts/workout-mode.ts — effectiveWorkoutMode + formatWorkoutSectionsText (the flat-text workout peek; a part opens with its own heading block — title, clock, optional, note)
• apps/web/src/components/overview/workouts/exercise-autocomplete.tsx, exercise-library-browser.tsx, exercise-video-dialog.tsx — exercise pickers
• apps/web/src/components/member/workouts/workout-detail-drawer.tsx — member’s read view of the snapshot (Plan tab: the day brief — workout.description — above the parts)
• apps/web/src/components/shared/verbatim/ — the coach-facing preview of the member app’s whiteboard, used by the workout page, the builder’s right rail and the paste review: verbatim-workout.tsx (the coach’s text line for line, movement marks → inline-demo-card.tsx, score lines in the org accent), from-builder-sections.ts (builder SectionState[] → the same input the stored workout gives it). Mirrors the app’s src/components/workout/verbatim-sections.tsx; the member web views keep shared/prescription/whiteboard-section.tsx
• apps/web/src/components/shared/workout-parts/ — section-parts.tsx (SectionParts: groups a workout’s blocks by groupSectionsIntoParts and puts each part under part-header.tsx’s PartHeader — title, class clock “0:00–11:00”, optional badge, part note; blocks outside a part render with no wrapper). Every section renderer goes through it: the member drawer, workout-execution-view.tsx, verbatim-workout.tsx (so the paste preview and the builder’s member preview too), shared/workout-section.tsx (feed / session drawer / program page / program-session sheet card), the course player and the paste preview’s whiteboard list
• apps/web/src/components/shared/prescription/superset-groups.ts — groupBySuperset for the whiteboard, prescribed and card renderers; a group whose movement carries group_load shows that load (and its progression) on the superset header instead of the movement row

DB (Drizzle, PostgreSQL)

All schema in libs/db/src/lib/schema/workouts.ts:

Comments: exercise_comments in libs/db/src/lib/schema/comments.ts. Attachments: attachments in libs/db/src/lib/schema/attachments.ts (polymorphic ownerType='exercise_comment').

Shared

Tests