# Architecture

MoonBVHKit separates format parsing, domain analysis, asset policy, and output
generation so each layer can be used independently by libraries, command-line
tools, CI jobs, and editor-side bridges.

## Data Flow

```text
BVH text
  -> tokenizer
  -> hierarchy and motion parser
  -> BvhDocument
  -> validation and analysis
  -> quality score and import profiles
  -> single or batch asset decisions
  -> Text / JSON / CSV / JUnit XML / Unity plan / Blender plan
```

## Layers

### Format Layer

`lexer.mbt` preserves token text and source positions. `parser.mbt` consumes the
tokens into the model defined by `types.mbt`. Parser errors retain stable error
codes, line and column positions, offending tokens, and readable messages.

### Query and Validation Layer

`query.mbt` provides read-only access to joints, paths, channel order, frame
values, rotations, and root position. `validation.mbt` checks invariants that
remain meaningful after parsing, including channel placement, channel offsets,
frame counts, frame widths, and frame timing.

### Analysis Layer

`analysis.mbt` computes clip statistics and channel ranges. `skeleton.mbt`
provides stable skeleton summaries, compatibility comparison, and conservative
retarget planning. `motion_tools.mbt` provides frame slicing, duration-preserving
resampling, time lookup, root-motion bounds, speed sampling, teleport detection,
and root-origin normalization.

### Asset Policy Layer

`quality.mbt` converts validation and motion signals into a deterministic score,
grade, and action. `profiles.mbt` applies named Unity, Blender, strict CI, and
preview policies to individual assets or named batches without importing an
editor SDK. This keeps policy decisions testable on every MoonBit target.

### Integration and Output Layer

`adapters.mbt` creates engine-neutral Unity and Blender metadata plans.
`exporters.mbt` and `report.mbt` produce deterministic Text, JSON, and CSV
representations for logs, dashboards, editor bridges, and asset gates. The CLI
in `cmd/main` demonstrates these outputs with a synthetic fixture.

## Design Properties

- Core behavior is implemented in MoonBit and has no native editor dependency.
- Parsing preserves unknown channels so validation can report them explicitly.
- Functions return deterministic values suitable for tests and CI comparison.
- Integration plans describe downstream work but never pretend to perform
  editor-side import, IK, retargeting, or coordinate conversion.
- Synthetic fixtures avoid redistribution and nondeterministic file dependencies.
- Public interface snapshots generated by `moon info` make API changes visible.

## Functional Boundary

Version 0.2.0 accepts ASCII BVH text and returns structured data, diagnostics,
statistics, policy decisions, and reports. It does not read files on behalf of
the host, bind to Unity or Blender, solve skeletons, bake rotations, retarget
animation, convert coordinate systems, or process FBX, glTF, and USD. Keeping
these operations outside the core package makes the library portable and gives
downstream tools a precise integration contract.