Comprehensive development guide for the Galatea robotics, kinematics, and fashion robotics domain.
Prerequisites#
Required Software#
| Tool | Version | Purpose |
|---|---|---|
| Node.js | >= 20.0 | Runtime for all Galatea libraries |
| pnpm | >= 10.0 | Package manager (workspace protocol) |
| Git | >= 2.40 | Version control |
| TypeScript | ^6.0.3 | Compile-time type checking (via catalog) |
Mathematical and Physics Background#
Developers working on the motion and kinematics layers should be familiar with:
- Linear algebra - Matrix operations, homogeneous transformations, quaternion rotations, Jacobian matrices
- Rigid body dynamics - Newton-Euler formulation, inertia tensors, torque computation
- Denavit-Hartenberg parameters - Standard and modified DH conventions for kinematic chain representation
- Control theory - PID control, impedance/admittance control, task-space and null-space optimization
- Coordinate frames - World, base, joint, and end-effector reference frames
Robotics-Specific Tooling (Optional)#
These tools are not required for library development but are useful for simulation and integration testing:
| Tool | Purpose |
|---|---|
| ROS 2 | Integration testing via @galatea/communication DDS bridge |
| Gazebo / MuJoCo | Physics simulation for testing kinematics and dynamics |
| URDF editors | Creating/editing robot description files |
| EtherCAT tools | Debugging real-time motor control communication |
Environment Variables#
No environment variables are required for building or unit-testing Galatea
libraries. All configuration is handled through the Zod-validated configuration
schemas in @galatea/core.
Project Structure#
The Galatea domain contains 20 libraries under libs/galatea/:
libs/galatea/
ai/ # VLA runtime, behavioral engine, RL, teleoperation
analytics/ # Engagement tracking, A/B testing, revenue attribution
choreography/ # Show designer, DSL, formations, music sync, lighting
communication/ # EtherCAT, CAN FD, DDS bridge, WiFi mesh, PTP sync
core/ # Foundation: types, constants, utils, errors, config
database/ # Persistence: pose-store, event-store, telemetry-store
event-handlers/ # Robot, safety, garment, show, customer event handlers
firmware/ # Motor drivers, sensor interfaces, RTOS, bootloader
fleet/ # Orchestrator, OTA updates, RaaS billing, diagnostics
garment-management/ # Outfit tracking, cloth manipulation, quick-change
hardware-abstraction/ # Joint interface, sensors, face/hand, thermal, RFID
inclusivity/ # Accessibility, body profiles, cultural config, i18n
kinematics/ # Forward/inverse kinematics, dynamics, collision, URDF
locomotion/ # Gait planning, balance, footstep planning, stairs
perception/ # Audience awareness, SLAM, depth, person detection
pose-engine/ # Breathing simulation, contrapposto, pose library
safety/ # ISO 13482 compliance, force limiting, emergency systems
sdk/ # TypeScript client SDK for external developers
simulation/ # Physics engine, cloth sim, digital twin, RL env
whole-body-control/ # Task-space, impedance, admittance, postural control
Individual Library Layout#
libs/galatea/<library>/
package.json # Name, version, ESM exports, zod dependency
project.json # Nx config with dependsOn: ["^build"]
tsconfig.json # Extends tsconfig.base.json
tsconfig.lib.json # Library compilation config
tsconfig.spec.json # Test compilation config
vitest.config.ts # Vitest config with project root
src/
index.ts # Barrel export + GALATEA_LIBRARY_ID constant
<module>/
index.ts # Module barrel
<file>.ts # Implementation
<file>.spec.ts # Co-located tests
Local Development Setup#
Initial Setup#
# Clone the repository
git clone git@github.com:GreyChimp/oshun.git
cd oshun
# Install all dependencies
pnpm install
No Infrastructure Required#
Galatea libraries are library-only and do not require running services. The
@galatea/database library defines persistence schemas but does not require a
running database for unit testing (schemas are validated structurally).
Building Libraries#
Build a Single Library#
pnpm nx build @galatea/core
Build All Galatea Libraries#
pnpm nx run-many --target=build --projects=tag:scope:galatea
Build Order#
Galatea libraries use "dependsOn": ["^build"] in their build targets, ensuring
that dependencies are built first. The build order follows:
@galatea/core(no dependencies)@galatea/hardware-abstraction,@galatea/safety(depend on core)@galatea/kinematics(depends on core, hardware-abstraction)@galatea/whole-body-control,@galatea/locomotion(depend on kinematics)- Higher-level libraries (fleet, choreography, ai, etc.)
Build Configuration#
{
"build": {
"executor": "@nx/js:tsc",
"dependsOn": ["^build"],
"outputs": ["{options.outputPath}"],
"options": {
"outputPath": "dist/libs/galatea/core",
"main": "libs/galatea/core/src/index.ts",
"tsConfig": "libs/galatea/core/tsconfig.lib.json",
"assets": []
}
}
}
Build output goes to dist/libs/galatea/<library>/.
Testing#
Run Tests for a Single Library#
pnpm nx test @galatea/core
Run All Domain Tests#
pnpm nx run-many --target=test --projects=tag:scope:galatea
Watch Mode#
npx vitest --config libs/galatea/kinematics/vitest.config.ts --watch
Test Configuration#
Galatea libraries use a vitest configuration that sets the root to the project
directory:
import { dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import { defineConfig } from 'vitest/config';
const projectRoot = dirname(fileURLToPath(import.meta.url));
export default defineConfig({
root: projectRoot,
test: {
globals: true,
environment: 'node',
include: ['src/**/*.{test,spec}.ts'],
coverage: {
provider: 'v8',
reporter: ['text', 'html', 'lcov'],
include: ['src/**/*.ts'],
exclude: ['src/**/*.{test,spec}.ts', 'src/**/index.ts'],
},
},
});
Key differences from other domains:
- Uses
import.meta.urlto resolve the project root directory - Coverage includes
lcovreporter (useful for CI coverage reporting) - Coverage excludes barrel
index.tsfiles
Coverage#
npx vitest --config libs/galatea/kinematics/vitest.config.ts --coverage
Coverage output lands in coverage/libs/galatea/<library>/.
Testing Patterns for Kinematics#
Forward kinematics tests should verify end-effector positions against known
DH parameter chains. Use toBeCloseTo for floating-point comparisons:
describe('forwardKinematics', () => {
it('computes end-effector position for a 2-link arm', () => {
const result = computeFK(jointAngles, dhParams);
expect(result.position.x).toBeCloseTo(expectedX, 6);
expect(result.position.y).toBeCloseTo(expectedY, 6);
});
});
Inverse kinematics tests should verify that the IK solution, when fed back through FK, returns the original target position within tolerance.
Collision detection tests should verify that known intersecting geometries report collisions and non-intersecting geometries do not.
Testing Patterns for Safety#
ISO 13482 compliance tests should verify that force limits are enforced and emergency stop transitions occur within specified time bounds.
Force limiting tests should verify that commanded torques are clipped to safe maximums and that the system transitions to a safe state when limits are exceeded.
Linting#
Lint a Single Library#
pnpm nx lint @galatea/kinematics
Lint All Galatea Libraries#
pnpm nx run-many --target=lint --projects=tag:scope:galatea
Common Development Tasks#
Adding a New Library#
- Create the directory:
mkdir -p libs/galatea/new-library/src
- Create
project.jsonwithdependsOn: ["^build"]:
{
"name": "@galatea/new-library",
"$schema": "../../../node_modules/nx/schemas/project-schema.json",
"sourceRoot": "libs/galatea/new-library/src",
"projectType": "library",
"tags": ["scope:galatea", "type:lib", "layer:domain"],
"implicitDependencies": ["@galatea/core"],
"targets": {
"build": {
"executor": "@nx/js:tsc",
"dependsOn": ["^build"],
"outputs": ["{options.outputPath}"],
"options": {
"outputPath": "dist/libs/galatea/new-library",
"main": "libs/galatea/new-library/src/index.ts",
"tsConfig": "libs/galatea/new-library/tsconfig.lib.json",
"assets": []
}
},
"lint": {
"executor": "@nx/eslint:lint",
"outputs": ["{options.outputFile}"],
"options": {
"lintFilePatterns": ["libs/galatea/new-library/**/*.ts"]
}
},
"test": {
"executor": "@nx/vite:test",
"outputs": ["{workspaceRoot}/coverage/libs/galatea/new-library"],
"options": {
"config": "libs/galatea/new-library/vitest.config.ts"
}
}
}
}
- Create
package.json:
{
"name": "@galatea/new-library",
"version": "0.1.0",
"description": "Galatea new-library module",
"type": "module",
"main": "./src/index.ts",
"types": "./src/index.ts",
"exports": {
".": {
"types": "./src/index.ts",
"import": "./src/index.ts"
}
},
"files": ["dist", "src"],
"dependencies": {
"zod": "catalog:"
},
"devDependencies": {
"typescript": "catalog:",
"vitest": "catalog:"
}
}
- Create
src/index.tswith the library identifier:
export * from './implementation/index.js';
export const GALATEA_LIBRARY_ID = '@galatea/new-library';
export const getGalateaLibraryId = (): string => GALATEA_LIBRARY_ID;
- Add path mapping to
tsconfig.base.json(Galatea uses per-library mappings rather than a wildcard pattern):
{
"@galatea/new-library": ["libs/galatea/new-library/src/index.ts"]
}
- Run
pnpm install.
Working with Zod Schemas#
All Galatea libraries use Zod for runtime schema validation. This is a domain convention enforced across all 20 libraries:
import { z } from 'zod';
export const JointAngleSchema = z.object({
joint: z.string(),
angle: z.number().min(-Math.PI).max(Math.PI),
velocity: z.number().optional(),
torque: z.number().optional(),
});
export type JointAngle = z.infer<typeof JointAngleSchema>;
Adding Sub-Module Path Exports#
Some Galatea libraries expose deep imports (e.g.,
@galatea/database/pose-store, @galatea/inclusivity/body-profiles). These
require explicit path mappings in tsconfig.base.json:
{
"@galatea/database/pose-store": [
"libs/galatea/database/pose-store/src/index.ts"
]
}
Key Patterns and Conventions#
Library Identifier Pattern#
Every Galatea library exports a GALATEA_LIBRARY_ID constant and a
getGalateaLibraryId() function:
export const GALATEA_LIBRARY_ID = '@galatea/kinematics';
export const getGalateaLibraryId = (): string => GALATEA_LIBRARY_ID;
This enables runtime module identification and is required for all libraries in the domain.
Dependency Layering#
The domain follows a strict five-layer architecture:
- Core (
@galatea/core) - Types, constants, utilities, errors - Hardware (
hardware-abstraction,firmware,safety,communication) - Motion (
kinematics,whole-body-control,locomotion,pose-engine) - Intelligence (
perception,ai,simulation) - Application (
fleet,choreography,garment-management,analytics,sdk)
Libraries may only depend on libraries at the same or lower layer. Never introduce upward dependencies.
Implicit Dependencies#
Galatea libraries declare implicitDependencies in their project.json to inform
Nx of the build order:
{
"implicitDependencies": ["@galatea/core", "@galatea/hardware-abstraction"]
}
Zod Validation Everywhere#
All public API inputs and configuration objects must be validated through Zod schemas. This provides runtime type safety for data coming from external systems (sensor readings, network messages, user configuration).
ESM Module System#
All libraries use ESM ("type": "module"). Import paths use .js extensions:
export * from './forward-kinematics/index.js';
export * from './inverse-kinematics/index.js';
Project Tags#
["scope:galatea", "type:lib", "layer:domain"]
Individual libraries may add additional tags like "galatea:core" or
"galatea:kinematics" for finer-grained filtering.
Debugging Tips#
Floating-Point Precision in Kinematics#
Kinematics computations involve many matrix multiplications that accumulate floating-point errors. When tests fail:
- Use
toBeCloseTo(expected, numDigits)where the precision threshold is5 * 10^(-numDigits - 1) - For position coordinates, 6 decimal places is typically sufficient
- For rotation matrices, verify orthogonality (R * R^T should be close to identity)
TypeScript Path Resolution#
Galatea uses per-library path mappings in tsconfig.base.json rather than a
wildcard. If a new library's imports fail to resolve, check that the specific
mapping has been added:
{
"@galatea/new-library": ["libs/galatea/new-library/src/index.ts"]
}
Build Order Failures#
If a library fails to build because a dependency is not yet built, verify:
implicitDependenciesis set in the failing library'sproject.json"dependsOn": ["^build"]is present in the build target- The dependency library's project.json is valid
Nx Cache Issues#
pnpm nx reset
Viewing the Dependency Graph#
pnpm nx graph --focus=@galatea/core
This visualizes the full dependency tree from core through all application layers.
Quick Reference#
| Action | Command |
|---|---|
| Install dependencies | pnpm install |
| Build one library | pnpm nx build @galatea/<lib> |
| Build all Galatea libraries | pnpm nx run-many --target=build --projects=tag:scope:galatea |
| Test one library | pnpm nx test @galatea/<lib> |
| Test all Galatea libraries | pnpm nx run-many --target=test --projects=tag:scope:galatea |
| Lint one library | pnpm nx lint @galatea/<lib> |
| Lint all Galatea libraries | pnpm nx run-many --target=lint --projects=tag:scope:galatea |
| Reset Nx cache | pnpm nx reset |
| View dependency graph | pnpm nx graph --focus=@galatea/core |