Agoge

A Convex component for sport training. Agoge models the full training domain: athletes, zones, target events, multi-week plans, mesocycle blocks, workouts with a FIT-shaped recursive step tree, and a workout-template library.

V1 is running-only. The schema is union-widened (v.literal("run") instead of hardcoded running fields) so cycling, swimming, and strength can be added later without a rewrite.

See agoge-schema.md for the full design: tables, indexes, the step-tree shape, the reasoning behind each decision.

Status

Foundational pass. The package currently exposes:

• The schema (7 tables with indexes)
• parseStepTree plus types and helpers for the recursive step tree

Mutations, queries, and derived helpers (zone resolution, compliance, workout lifecycle) are not yet implemented.

Installation

pnpm add @nativesquare/agoge

Register the component in your app's Convex config:

// convex/convex.config.ts
import { defineApp } from "convex/server";
import agoge from "@nativesquare/agoge/convex.config.js";

const app = defineApp();
app.use(agoge);

export default app;

Step-tree validation

The step tree is validated at the mutation boundary via Zod (Convex validators don't support recursion). When mutations are added, they'll call parseStepTree before persisting to workouts.structure or workoutTemplates.structure.

import { parseStepTree } from "@nativesquare/agoge";

const tree = parseStepTree(input); // throws ZodError on malformed input

Development

pnpm install
pnpm run dev

pnpm run dev runs the backend, the example frontend, and a watcher that rebuilds the component on change.

Layout

src/
  component/
    schema.ts       7 Agoge tables
    stepTree.ts     Zod schema for the step tree, types, helpers
    convex.config.ts
  client/index.ts   Agoge class wrapping the component API
  react/index.ts    React hooks (placeholder)
  test.ts           convex-test registration helper
example/            Convex app that consumes the component (stub for now)