Add documenation of all apps/packages

2026-07-31 09:42:53 -04:00
parent e299d1e5cc
commit cc7bf5d8d8
9 changed files with 356 additions and 25 deletions
@@ -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