Add documenation of all apps/packages

packages/calculator/README.md

@@ -0,0 +1,39 @@
+# @blade-and-brawn/calculator
+
+Turns a player's raw activity performances (e.g. squat weight, mile time) into
+per-attribute and overall "levels", by generating and interpolating strength/
+performance standards across age, weight, and gender.
+
+For the algorithm itself and the external standards it's based on, see
+[`docs/level-calculator.md`](../../docs/level-calculator.md) at the repo root.
+
+## Exports
+
+- `LevelCalculator` — takes a `Standards` instance; `calculate(player, activityPerformances)`
+  returns a level per `Attribute` plus an overall player level.
+- `Standards` — takes a `StandardsConfig` (raw `StandardsData` + generation
+  `StandardsParams`) and builds the full interpolatable standards table
+  (stretching to more levels, generating missing ages/weights, etc.).
+- Typebox schemas for the above (`models.ts`), re-exported from the package root.
+
+## Usage
+
+`StandardsConfig` normally comes from the database (see
+`apps/api/src/services/calculator.ts`), not a static file, since standards
+configs/datasets are editable from the admin portal:
+
+```ts
+import { LevelCalculator, Standards, type StandardsConfig } from "@blade-and-brawn/calculator";
+
+const config: StandardsConfig = /* fetched from storage */;
+const calculator = new LevelCalculator(new Standards(config));
+
+const { player, attributes } = calculator.calculate(playerMetrics, activityPerformances);
+```
+
+## Structure
+
+- `src/index.ts` — `LevelCalculator` and `Standards`
+- `src/models.ts` — typebox schemas and types
+- `src/avg-weights.ts` + `src/data/avg-weights.json` — average bodyweight by
+  age/gender, used when generating age-based standards

packages/calculator/src/index.ts

@@ -13,16 +13,6 @@ import { levenbergMarquardt as LM } from "ml-levenberg-marquardt";
 import { getAvgWeight } from "./avg-weights";
 import { type LevelCalculatorOutput, type Levels, type NumberMetric, type Standard, type StandardsConfig, type StandardsData } from "./models";
 
-// SOURCES
-// Squat, Bench, Dead Lift:
-//  http://lonkilgore.com/resources/Lon_Kilgore_Strength_Standard_Tables-Copyright-2023.pdf
-// 1 mile run:
-//  https://runninglevel.com/running-times/1-mile-times
-// Broad Jump:
-//  https://nrpt.co.uk/training/tests/power/broad.htm
-// 3 Cone drill:
-// https://nflsavant.com/combine.php?utm_source=chatgpt.com
-
 export * from "./models";
 
 const metricPriority = (m: NumberMetric) => {

packages/commerce/README.md

@@ -1,12 +1,30 @@
-# Printful
+# @blade-and-brawn/commerce
 
-## Definitions
+Printful and Webflow API clients, plus the `ProductSyncer` that keeps Webflow
+CMS products/SKUs in sync with Printful's catalog.
 
-- "Color-grouped" products
-    - Products in this format: "Product Name [color]"
-    
-## Constraints
+## Exports
 
-1. Color-grouped products should no more than *one* printful color variant
-2. The single color-grouped product variant should match [color] 
-3. Printful product names should be unique
+- `PrintfulClient` — `new PrintfulClient({ storeId, token, webhookSecret })`;
+  products, webhooks.
+- `WebflowClient` — `new WebflowClient({ siteId, collectionIds: { products, skus }, token, webhookSecret })`;
+  CMS products/SKUs, webhooks.
+- `ProductSyncer` — `new ProductSyncer(printful, webflow)`; `syncApparel(options)`
+  pulls Printful products and upserts them into the Webflow collections,
+  respecting the naming conventions below.
+- Shared `Printful`/`Webflow` request/response types (`util/types.ts`) and misc
+  helpers (`util/misc.ts`, e.g. `formatSlug`).
+
+## Printful product naming conventions
+
+- "Color-grouped" products follow the format `Product Name [color]`.
+
+Constraints:
+
+1. A color-grouped product should have no more than *one* Printful color variant.
+2. That single color-grouped product's variant should match `[color]`.
+3. Printful product names should be unique.
+
+See `apps/api/src/scripts/register-webhooks.ts` for how webhooks are
+registered against the API's domain, and `apps/api/src/services/commerce.ts`
+for how `ProductSyncer` is invoked.

packages/domain/README.md

@@ -0,0 +1,24 @@
+# @blade-and-brawn/domain
+
+Shared models, enums, and utility functions with no dependencies on any other
+workspace package — used by `packages/calculator`, `packages/commerce`,
+`apps/api`, and `apps/portal` to avoid duplicating core types.
+
+## Exports
+
+### Models (`src/models.ts`)
+
+- `Attribute` — `Strength` / `Power` / `Endurance` / `Agility`
+- `Activity` — `BackSquat` / `Deadlift` / `BenchPress` / `Run` / `BroadJump` / `ConeDrill`
+- `Gender` — `Male` / `Female`
+- `Metrics` / `Player` / `ActivityPerformance` — typebox schemas + types for a
+  player's age/weight/gender and their performance on a given activity
+
+### Utils (`src/utils.ts`)
+
+- Unit conversions: `lbToKg`, `kgToLb`, `minToMs`, `secToMs`, `msToMin`,
+  `ftToCm`, `inToCm`, `cmToIn`, `msToTime`
+- `range(length)`, `clamp(x, lo, hi)`
+- `parseRetryAfterMs(header, defaultMs)` — parses a `Retry-After` header
+  (seconds or HTTP date) for backoff, used by the Printful/Webflow clients
+- `RateLimitError` — thrown by `packages/commerce` clients on HTTP 429