# Galatea — Systems Deep Dive

> The `libs/galatea/` area: a humanoid-robotics software stack for
> fashion-retail and entertainment robots — kinematics, whole-body control,
> locomotion, embedded firmware, perception, ISO 13482 safety, choreography,
> fleet ops, garment handling, and AI — built as ~37 Nx projects that mix
> TypeScript domain logic with `no_std` Rust crates for the real-time/embedded
> paths.

## What this area is

Galatea (named for Pygmalion's statue brought to life) is a library-only domain
that implements a full robotics stack for humanoid "robot mannequin" platforms.
It spans from low-level motor firmware up through kinematics, balance,
perception, behavioural AI, and multi-robot show choreography. Every project
carries the `scope:galatea`, `type:lib`, `layer:domain` Nx tags and a
`galatea:<name>` tag, and every TypeScript library exports a
`GALATEA_LIBRARY_ID` constant plus a `getGalateaLibraryId()` accessor for
runtime module identification.

The area is **polyglot by design**, exactly as the monorepo's stack policy
prescribes (TypeScript by default, Rust where performance/real-time requires
it). The performance-critical and embedded layers — `kinematics`,
`whole-body-control`, `locomotion`, `pose-engine`, `hardware-abstraction`,
`firmware`, and `communication` — ship companion Rust crates (`#![no_std]` for
the on-robot paths). Two patterns appear. In `hardware-abstraction` and
`firmware` the Rust crate **is** the implementation and the TypeScript surface
is a thin, typed `*-rust-manifest.ts` descriptor that records the crate path,
target profile, and capability list (e.g. `CANFD_INTERFACE_RUST_MANIFEST`). In
`kinematics`, `whole-body-control`, `locomotion`, `pose-engine`, and
`communication` there is a **full TypeScript implementation alongside** a
companion Rust crate, linked by the same manifest convention — so a node like
`inverse-kinematics` has both a TS solver (`inverse-kinematics.ts`) and a Rust
hierarchical-QP solver (`rust-inverse-kinematics/src/inverse_kinematics_qp.rs`,
`JOINT_COUNT = 52`).

I verified the Rust is real, not scaffold: the small (3–5 line) `lib.rs` files
are crate roots that delegate via `pub mod` to sibling modules, and summing each
crate's `.rs` files gives 95–2474 lines of genuine domain code per crate (FOC
park/clarke motor control, EtherCAT/CAN-FD/DDS/PTP/WiFi-mesh comms, stereo SLAM,
QP IK, etc.). An adversarial stub scan across the area came back clean — the
only `Math.random()` in non-test code is annotated retry-backoff jitter in
`core/src/errors/error-recovery.ts`, and the only `placeholder()` is a
`const fn` array-seed in the Rust auto-tuning module.

## How the area is shaped

The dependency graph (per `docs/domains/galatea/README.md`) layers bottom-up:
`@galatea/core` (shared types/constants/utils/errors) underpins the hardware,
motion, and safety layers; perception and safety sit beside hardware; kinematics
/ whole-body-control / locomotion form the motion tier; `@galatea/ai` is the
intelligence tier; and the application tier (`fleet`, `choreography`,
`garment-management`, `simulation`, `analytics`) plus the developer `sdk` sit on
top. Three projects — `@galatea/database`, `@galatea/event-handlers`, and
`@galatea/inclusivity` — are **namespace parents**: their own `src/index.ts`
carries only the library-ID marker, while the substantive code lives in
independently-importable child projects (e.g. `@galatea/database/pose-store`).
`@galatea/sdk` is a hybrid parent+client: its `src/index.ts` re-exports the
in-project TS client (`client-ts`) and the `client-python` manifest, so it is
not a pure marker-only aggregation root.

## How it fits the wider system

These are libraries, not running services — there is no Galatea app process
here; consumers compose the libraries. Higher tiers import lower ones directly
(the IK solver imports `GALATEA_JOINT_KINEMATIC_CHAIN` and
`GALATEA_JOINT_LIMITS` from `@galatea/core`; the SDK client wraps
fleet/show/analytics operations). The embedded Rust crates target on-robot
controllers (`edge-linux` / `rt-preempt` profiles) and are referenced from
TypeScript only as manifests, so the build graph stays buildable in a Node
toolchain while the real-time code is compiled for the robot. External
integrators consume the `@galatea/sdk` family — a TypeScript client and a typed
Python package (`galatea_client`). Walk the "used by" edges on any node below to
see exact consumers.

## Entity reference

### @galatea/core

The foundational library every other Galatea node depends on
(`libs/galatea/core/src`). It owns the shared domain vocabulary: `types/`
(pose/motion, `robot-state`), `utils/` (`quaternion.ts`, `se3.ts`,
`trajectory-interpolation.ts`, `procedural-motion.ts`), `constants/`
(`physical-constants`, `morphing-constants`, `safety-thresholds`),
`config/runtime-config.ts`, and `errors/` (a structured `error-taxonomy` plus
`error-recovery` with exponential-backoff-with-jitter). It exports the canonical
kinematic chain (`GALATEA_JOINT_KINEMATIC_CHAIN`), joint limits,
`toRotationMatrix`, and `Quaternion`/`Vector3` types consumed across the motion
stack. Real, ~5k lines of TypeScript.

### @galatea/kinematics

Computational kinematics (`libs/galatea/kinematics/src`) with both TypeScript
and Rust solvers across six modules: `forward-kinematics`
(`computeFullBodyForwardKinematics`), `inverse-kinematics`, `dynamics`,
`collision-geometry`, `jacobian-computation`, and `urdf-parser`. Each module
pairs a real TS implementation with a companion `#![no_std]` Rust crate linked
by a `*-rust-manifest.ts`; for example `inverse-kinematics.ts` solves a
prioritised multi-task (end-effector / COM / gaze / posture)
damped-least-squares problem in TS, while `rust-inverse-kinematics` implements a
hierarchical QP over `JOINT_COUNT = 52` with joint/velocity constraints.
Substantial and genuine on both sides.

### @galatea/whole-body-control

Whole-body / operational-space control (`libs/galatea/whole-body-control/src`):
`task-space-controller`, `impedance-controller`, `admittance-controller`,
`postural-controller`, `center-of-mass`, and `momentum-controller`. Each is a
real TS controller with a companion Rust crate (95–190 lines of `.rs` per crate,
e.g. `rust-momentum-controller`) for the real-time path. It provides the
compliant- interaction and balance-regulation layer that locomotion and the AI
tiers drive.

### @galatea/locomotion

The largest motion library (`libs/galatea/locomotion/src`, ~15.6k TS lines, 29
spec files). Beyond the classic bipedal controllers — `gait-planner`,
`balance-controller`, `footstep-planner`, `step-controller`, `push-recovery`,
`stair-navigation`, `walking-styles` (each with a companion Rust crate) — it
carries an extensive **procedural-animation** suite the domain README
under-documents: `procedural-walk-cycle`, `procedural-bird-flight`,
`procedural-fish-swimming`, `procedural-snake-locomotion`,
`procedural-arthropod-locomotion`, `procedural-quadruped-locomotion`,
`procedural-reach-and-grab`, `procedural-head-look-at`, `procedural-lip-sync`,
`procedural-emotion-blending`, `procedural-appendage-animation`,
`secondary-motion`, `terrain-adaptive-foot-placement`,
`wind-reactive-fabric-hair`, and `control-rig-integration`. All real TypeScript.

### @galatea/pose-engine

Humanoid pose generation and validation (`libs/galatea/pose-engine/src`):
`breathing-simulator`, `contrapposto-solver`, `hand-pose-library`,
`micro-movement-gen`, `pose-library`, `pose-optimizer`, `pose-validation`, and
`transition-planner`. It produces the lifelike "presence" behaviours (subtle
breathing, micro-movement, classical contrapposto stances) plus joint-limit and
garment-safety validation (`JointLimitViolation`, `GarmentSafetyViolation`
types). Each module has a real TS implementation backed by a companion Rust
crate.

### @galatea/hardware-abstraction

The hardware abstraction layer (`libs/galatea/hardware-abstraction/src`).
**Rust-primary**: every module's TypeScript `index.ts` re-exports only a typed
`*-rust-manifest.ts` descriptor (the TS surface is ~220 lines total), while the
real implementation is `#![no_std]` Rust — `joint-interface`,
`actuator-profiles` (with auto-tuning), `sensor-fusion`, `body-morphing`,
`face-system`, `hand-system`, `thermal-management`, `rfid-reader`, and
`tactile-skin`, each crate 548–1672 lines of genuine code. The manifests record
crate path, target profile, and capabilities for the build graph; the algorithms
live in the crates.

### @galatea/firmware

Low-level embedded firmware (`libs/galatea/firmware/src`), also **Rust-primary**
with TS reduced to driver manifests (~396 TS lines). The crates are real and
sizeable `#![no_std]` embedded code: `motor-drivers/rust-foc` (~2.5k lines of
field-oriented control — Clarke/Park transforms, current protection, multi-mode
control, motor identification), `safety-controller` (~2.1k lines),
`power-management`, `comms-bus`, `rtos-runtime`, `bootloader`, `board-support`,
and a `sensor-interfaces` family of device drivers (`rust-bno085` IMU,
`rust-mini45` F/T, `rust-vl53l5cx` ToF, `rust-tactile-skin`,
`rust-foot-pressure`), each 440–675 lines.

### @galatea/communication

Robot communication protocols (`libs/galatea/communication/src`). Unlike
firmware and hardware-abstraction, this library has **both** a real TS surface
and companion Rust crates per protocol: `ethercat-master`, `canfd-interface`,
`dds-bridge` (ROS 2 interop), `wifi-mesh` (multi-robot mesh, ~1.2k-line crate),
`cloud-connector`, and `ptp-sync` (IEEE 1588). The `*-rust-manifest.ts` files
(e.g. `CANFD_INTERFACE_RUST_MANIFEST`) bind each TS module to its crate and
record edge-Linux/RT-PREEMPT targets and capability sets. All six crates are
substantial (443–1245 lines).

### @galatea/perception

Computer vision and environment understanding (`libs/galatea/perception/src`),
TypeScript-only and substantial (~6.1k lines): `audience-awareness`,
`camera-only-perception`, `depth-processing`, `fit-analysis`,
`garment-recognition`, `obstacle-detection`, `person-detection`, `slam`, and
`visual-servoing`. The `slam` module (~848 lines) models a stereo visual-SLAM
pipeline with calibration, feature observations, landmarks, keyframes,
loop-closure events, and a mapping/localization-only mode switch.

### @galatea/safety

ISO 13482 personal-care-robot safety infrastructure (`libs/galatea/safety/src`,
~5.1k TS lines): `iso-13482` (operating-state machine, HAZOP guide-word
analysis, ISO 12100 risk assessment with `Iso12100RiskLevel` low→intolerable),
`risk-assessment`, `force-limiting`, `emergency-systems`, `functional-safety`
(watchdogs), `regulatory-toolkit`, `audit-logger` (tamper-aware event logging),
and `access-control`. Real, domain-specific safety-standard modelling rather
than generic CRUD.

### @galatea/ai

The intelligence tier (`libs/galatea/ai/src`, ~15.9k TS lines, 22 spec files)
with sixteen modules barrelled from `index.ts`: `vla-runtime`,
`behavioral-engine`, `natural-motion-gen`, `customer-engagement`,
`llm-interaction`, `emotion-expression`, `fashion-trend-ai`,
`attention-prediction`, `reinforcement-learning`, `quiet-locomotion`,
`end-to-end-control` (with `reflex-vla-runtime`), `large-behavior-model`
(flow-matching/diffusion-transformer training config plus an
`lbm-evaluation-suite`), `motor-cortex-policy`, `teleoperation`,
`data-collection` (plus `training-data-management`), and
`training-infrastructure`. These are deterministic,
configuration-and-orchestration implementations of the model pipelines (types,
schedules, evaluation), not bundled model weights.

### @galatea/choreography

Multi-robot show authoring and performance (`libs/galatea/choreography/src`,
~9.8k lines): `show-designer`, `show-dsl` (a ~1.2k-line domain-specific language
with show/robot declarations, track/formation/cue/parallel statements and cue
departments), `formation-engine`, `music-sync`, `lighting-bridge` (DMX/ArtNet),
`stage-mapper`, `timing-engine`, `rehearsal-engine`, and `show-scheduler`. It is
the application-tier system that turns choreography into coordinated robot
motion and stage effects.

### @galatea/fleet

Multi-robot fleet operations (`libs/galatea/fleet/src`, ~8.3k lines):
`orchestrator` (task allocation), `health-monitoring`, `scheduling-engine`,
`ota-updates`, `raas-billing` (Robotics-as-a-Service metering),
`remote-diagnostics`, `capacity-planning`, `incident-management`,
`federated-learning`, and `digital-nervous-system` (fleet-wide telemetry
aggregation and anomaly detection). All real TypeScript application logic.

### @galatea/garment-management

Clothing and costume handling (`libs/galatea/garment-management/src`, ~3.8k
lines): `outfit-tracking` (RFID/vision inventory), `digital-product-passport`
(provenance), `cloth-manipulation` (grasp/pull/drape primitives with
`garmentlab`/`isaac-sim` policy-training backends and dual-arm support),
`quick-change`, `fit-validation`, `wardrobe-scheduler`, `fabric-safety`, and
`size-adaptation`. This is the fashion-specific layer that distinguishes Galatea
from a generic robot stack.

### @galatea/simulation

Physics simulation and digital twin (`libs/galatea/simulation/src`, ~7.9k
lines): `physics-engine` (~1.5k lines, `mujoco`/`isaac-sim` backends,
`urdf`/`mjcf` model loading, contact/friction/damping parameter sets),
`cloth-simulator`, `digital-twin`, `show-preview`, `rl-training-env` (Gym-like),
`wear-simulator`, `virtual-showroom`, and `scenario-tester`. Real
simulation-orchestration TypeScript; the heavy physics backends are integration
targets, modelled here as typed parameter/interface layers.

### @galatea/analytics

Engagement and business analytics (`libs/galatea/analytics/src`, ~8.7k lines):
`engagement-tracker`, `ab-testing`, `heatmap-engine` (store-traffic heatmaps),
`pos-integration`, `inventory-bridge`, `revenue-attribution` (~1.1k lines
modelling robot-vs-static-mannequin display-variant attribution with
exposure/sale events and cost models), and `reporting-dashboard`. Real
attribution and experimentation logic, not stubs.

### @galatea/database

A **namespace-parent** library (`libs/galatea/database/src`): its own `index.ts`
carries only `GALATEA_LIBRARY_ID` and `getGalateaLibraryId()`. The substantive
persistence code lives in five independently-importable child store projects
(below). It is an intentional thin aggregation root, not an empty scaffold.

### @galatea/database/pose-store

Pose persistence (`libs/galatea/database/pose-store/src/pose-store.ts`, ~757
lines). A real store defining pose record schemas, validation, and query/append
operations for the pose-engine data — re-exported from the one-line `index.ts`.

### @galatea/database/event-store

Operational/safety event persistence
(`libs/galatea/database/event-store/src/event-store.ts`, ~658 lines). Defines
event-domain and severity taxonomies (`EventDomain`, `EventSeverity`),
operational-event record schemas, append inputs, and SQL schema generation
(`EventStoreSchemaSql`, `EventStoreSchemaOptions`). Real, domain-specific.

### @galatea/database/telemetry-store

Telemetry persistence
(`libs/galatea/database/telemetry-store/src/telemetry-store.ts`, ~1.3k lines —
the largest store). Handles time-series robot telemetry record schemas and
aggregation/query operations. Real implementation.

### @galatea/database/garment-store

Garment data persistence
(`libs/galatea/database/garment-store/src/garment-store.ts`, ~1.0k lines). The
store for outfit/garment records backing `garment-management`, with schemas and
query operations. Real implementation.

### @galatea/database/show-store

Show/choreography persistence
(`libs/galatea/database/show-store/src/show-store.ts`, ~865 lines). Stores show
definitions, schedules, and performance records backing the choreography and
fleet scheduling tiers. Real implementation.

### @galatea/event-handlers

A **namespace-parent** library (`libs/galatea/event-handlers/src`): `index.ts`
holds only the library-ID marker. The real event-processing logic lives in five
child handler projects (below), one per event family.

### @galatea/event-handlers/robot-events

Robot lifecycle/status event processing
(`libs/galatea/event-handlers/robot-events/src/robot-events.ts`, ~1.6k lines —
the largest handler). Models robot lifecycle states, subsystem states,
registration, boot self-test sequences (`BootSelfTestCheck`, `SelfTestReport`),
and status transitions. Real, domain-specific.

### @galatea/event-handlers/safety-events

Safety-system event processing
(`libs/galatea/event-handlers/safety-events/src/safety-events.ts`, ~849 lines).
Handles emergency-stop, hazard, and safety-state-transition events from the
`@galatea/safety` layer. Real implementation.

### @galatea/event-handlers/show-events

Show-performance event processing
(`libs/galatea/event-handlers/show-events/src/show-events.ts`, ~1.1k lines).
Processes cue/timing/performance events emitted during choreographed shows. Real
implementation.

### @galatea/event-handlers/garment-events

Garment-interaction event processing
(`libs/galatea/event-handlers/garment-events/src/garment-events.ts`, ~627
lines). Handles outfit-change, fit, and garment-tracking events. Real
implementation.

### @galatea/event-handlers/customer-events

Customer-interaction event processing
(`libs/galatea/event-handlers/customer-events/src/customer-events.ts`, ~470
lines). Processes engagement/interaction events feeding the analytics and
customer-engagement layers. Real implementation.

### @galatea/inclusivity

A **namespace-parent** library (`libs/galatea/inclusivity/src`) holding only the
library-ID marker; the real inclusivity logic lives in four child projects
(below). Thin aggregation root.

### @galatea/inclusivity/body-profiles

Body-profile configuration
(`libs/galatea/inclusivity/body-profiles/src/body-profiles.ts`, ~667 lines).
Defines body-shape and gender-presentation taxonomies, US/EU sizing scales
(`WOMENS_US_SIZES`, `MENS_ALPHA_SIZES`), and a `BodyProfileRegistry`
(`createBodyProfileRegistry()`) for diverse body-type configuration. Real
domain-specific code.

### @galatea/inclusivity/accessibility

Accessibility adaptations
(`libs/galatea/inclusivity/accessibility/src/accessibility.ts`, ~1.4k lines —
the largest inclusivity module). Implements accessibility configuration and
adaptation logic for diverse user needs. Real implementation.

### @galatea/inclusivity/cultural-config

Cultural customization
(`libs/galatea/inclusivity/cultural-config/src/cultural-config.ts`, ~1.4k
lines). Configures market/region-specific customizations (etiquette, gestures,
presentation norms) for international deployment. Real implementation.

### @galatea/inclusivity/multilingual

Multilingual support
(`libs/galatea/inclusivity/multilingual/src/multilingual.ts`, ~925 lines).
Handles language configuration and localization for international robot
deployment. Real implementation.

### @galatea/sdk

A **namespace-parent** plus the TypeScript developer client
(`libs/galatea/sdk/src`). Its `index.ts` re-exports `client-ts/client.ts` (~1.1k
lines: fleet/show/analytics operations and realtime robot-status subscriptions —
`FleetRobotStatus`, `ScheduleShowRequest`, `startDueSchedules`, etc.) and a
`client-python/index.ts` that is a typed **manifest**
(`GALATEA_PYTHON_CLIENT_SDK_MANIFEST`) pointing at the separate Python package.
The two SDK extension projects (`analytics-sdk`, `show-sdk`) and the Python
client are independent sibling projects.

### @galatea/sdk/analytics-sdk

A developer SDK extension for analytics
(`libs/galatea/sdk/analytics-sdk/src/analytics-sdk.ts`, ~1.2k lines). Provides
custom-event schema definitions, event tracking, and aggregate/ratio metric
definitions for instrumenting and querying Galatea analytics. Real
implementation.

### @galatea/sdk/show-sdk

A developer SDK extension for show authoring
(`libs/galatea/sdk/show-sdk/src/show-sdk.ts`, ~943 lines). Offers builders for
path/pose/pivot tracks and formation templates, music-sync point import, and a
show validation/timing report (`ShowValidationReport`,
`ShowValidationTimingSummary`). Real implementation.

### @galatea/sdk/client-python

A typed Python client package (`libs/galatea/sdk/client-python`,
`pyproject.toml`, package `galatea_client`). It exposes `GalateaClient` with
`FleetClient`, show, and analytics sub-clients over a backend abstraction
(`backend.py`), `models.py` dataclasses, a `py.typed` marker, and
`tests/test_client.py`. The shipped backend is an `InMemoryGalateaBackend`, so
the package is exercisable end-to-end against an in-memory implementation rather
than a live service. Real, typed Python — the only non-TypeScript/Rust SDK in
the area.