Galatea Domain — Architecture

Galatea — Robotics, Kinematics, and Fashion Robotics Platform

Galatea is the Oshun monorepo's robotics domain. It provides the complete software stack for humanoid robots that operate in fashion retail and entertainment environments — from bare-metal motor control firmware up through computer vision, AI behavioral engines, and coordinated multi-robot show orchestration. The name comes from the mythological statue brought to life by Pygmalion, reflecting the domain's purpose: giving physical robots the intelligence to perceive, move, interact, and perform.

The domain is consumed by show operators and retail integrators who use the developer SDK to register robots, author choreographies, and query business analytics. It is also consumed by robot firmware targets written in Rust, which implement the low-level control loops that the TypeScript layers orchestrate.

As a pure library domain, Galatea has no apps/ or services/ projects. All functionality is exported as a set of 36 buildable packages under libs/galatea/. Higher-level products (retail point-of-sale, fashion-show management interfaces) live in other domains and will integrate with Galatea through the SDK and planned cross-domain APIs.

Library Organization#

The 20 module directories under libs/galatea/ span the full robotics stack. Four of them (database, event-handlers, inclusivity, sdk) are sub-divided into per-concern packages. The tree below shows the full layout.

libs/galatea/
├── core/                         # Foundation types, coordinate frames, error codes, config
├── kinematics/                   # FK, IK solvers, dynamics, collision, URDF parsing
├── hardware-abstraction/         # Unified actuator/sensor API across hardware platforms
├── locomotion/                   # Bipedal gait planning, balance, navigation
├── whole-body-control/           # Task-space control, impedance, admittance, CoM control
├── perception/                   # Computer vision, SLAM, depth processing, visual servoing
├── ai/                           # VLA models, behavioral engine, LLM integration, RL
├── safety/                       # ISO 13482, force limiting, E-stop, safety monitoring
├── pose-engine/                  # Named pose library, interpolation, sequencing
├── choreography/                 # Show choreography definition and execution
├── garment-management/           # Garment inventory, RFID, outfit tracking
├── fleet/                        # Fleet registry, monitoring, OTA updates, maintenance
├── simulation/                   # Physics simulation, digital twin, policy training
├── communication/                # Robot messaging, telemetry streaming, coordination
├── firmware/                     # Firmware version management and OTA delivery
├── analytics/                    # Engagement analytics, A/B testing, revenue attribution
├── inclusivity/                  # Body profiles, accessibility, cultural config, multilingual
│   ├── accessibility/
│   ├── body-profiles/
│   ├── cultural-config/
│   └── multilingual/
├── database/                     # Persistence layer (5 specialized stores)
│   ├── event-store/
│   ├── garment-store/
│   ├── pose-store/
│   ├── show-store/
│   └── telemetry-store/
├── event-handlers/               # Domain event handler modules
│   ├── customer-events/
│   ├── garment-events/
│   ├── robot-events/
│   ├── safety-events/
│   └── show-events/
└── sdk/                          # Developer SDKs
    ├── analytics-sdk/
    ├── show-sdk/
    └── client-python/

Total: 20 module directories → 36 buildable packages (0 applications, 0 standalone services). The database, event-handlers, inclusivity, and sdk directories each contain one package per sub-directory plus an aggregator project.json. The sdk directory additionally holds the client-python Python package (galatea-client-sdk).

Architectural Layers#

The packages are organized into seven horizontal layers, each building on the one below. The diagram below shows which packages belong to each layer. A new engineer should read this from the bottom up: @galatea/core establishes shared vocabulary; the hardware interface layer abstracts physical differences between robot platforms; motion and intelligence layers build on top; the SDK and event-handler packages at the top compose the lower layers for consumers.

┌─────────────────────────────────────────────────────────────────────┐
│  CONSUMER LAYER                                                     │
│  @galatea/sdk · @galatea/sdk/show-sdk · @galatea/sdk/analytics-sdk │
│  @galatea/sdk/client-python                                         │
├─────────────────────────────────────────────────────────────────────┤
│  ORCHESTRATION LAYER                                                │
│  @galatea/choreography · @galatea/fleet · @galatea/analytics       │
├─────────────────────────────────────────────────────────────────────┤
│  INTELLIGENCE LAYER                                                 │
│  @galatea/ai · @galatea/perception · @galatea/pose-engine          │
│  @galatea/garment-management · @galatea/inclusivity                │
├─────────────────────────────────────────────────────────────────────┤
│  MOTION LAYER                                                       │
│  @galatea/whole-body-control · @galatea/locomotion                 │
├─────────────────────────────────────────────────────────────────────┤
│  HARDWARE INTERFACE LAYER                                           │
│  @galatea/hardware-abstraction · @galatea/kinematics               │
│  @galatea/safety · @galatea/firmware                               │
├─────────────────────────────────────────────────────────────────────┤
│  INFRASTRUCTURE LAYER                                               │
│  @galatea/database · @galatea/communication · @galatea/simulation  │
│  @galatea/event-handlers                                           │
├─────────────────────────────────────────────────────────────────────┤
│  FOUNDATION                                                         │
│  @galatea/core                                                      │
└─────────────────────────────────────────────────────────────────────┘

Core Design Patterns#

1. Hardware Abstraction First#

The @galatea/hardware-abstraction library defines a unified joint and sensor API so that all upper-layer control software is hardware-agnostic. A new robot platform is integrated by implementing the hardware abstraction interfaces — the kinematics, locomotion, and AI layers require no changes.

This enables the same choreography and show software to run on different humanoid robot hardware without modification.

2. ISO 13482 Safety Architecture#

Safety is not a feature — it is an architectural constraint. @galatea/safety runs as a watchdog over every motion command:

• Every IK request passes through force and torque limit validation before execution.
• Human proximity zones trigger speed reduction or stop before the control loop can violate them.
• Hardware E-stop is independent of software and cannot be bypassed programmatically.
• All safety events are emitted to the event bus and written to the append-only event store.
• ISO 13482 compliance status is continuously evaluated and exposed via API.

3. Event-Sourced Domain Handlers#

The five @galatea/event-handlers sub-packages (customer, garment, robot, safety, show events) are in-process stateful engines, not message-bus subscribers. Each defines a frozen event-type constant array, ingests typed domain inputs, mutates internal state, appends to an in-memory event log, and exposes a filterable event history (listEvents(...)). This design choice has three practical benefits:

• Individual handlers can be tested in isolation with no infrastructure.
• A single replayable event timeline per handler supports post-incident analysis.
• The handler engines can be composed by the SDK or by future services without coupling to a specific message broker.

A separate append-only audit log is available in @galatea/core (InMemoryImmutableRecoveryEventStore) and the persistent event-store package. The runtime config (@galatea/core) carries Redis/NATS/MQTT connection settings, but the event-handler packages themselves do not bind to a broker.

4. Specialized Database Stores#

Rather than a single monolithic schema, Galatea separates persistence into five purpose-built stores. Each store is optimized for the read/write pattern of its data — for example, telemetry is never updated in place (time-series insert), while the pose library needs vector similarity search.

5. Simulation-First Development#

@galatea/simulation provides a physics simulation environment that mirrors the production deployment. All new behaviors, locomotion controllers, and show choreographies are developed and validated in simulation before being deployed to physical robots. The digital twin maintains synchronization between the simulated and physical robot states.

Real-Time Control Architecture#

Robots are not single-threaded systems. Control tasks run at different frequencies because different problems operate on different timescales — motor current must be regulated thousands of times per second, while behavioral decisions change only tens of times per second. The table below shows the intended control loop hierarchy and each loop's responsibilities.

The hardware control and WBC loops are designed to run on the Rust firmware and RTOS targets (currently described by the *-rust-manifest.ts manifests in @galatea/firmware), while the higher-level TypeScript libraries run as standard Node.js processes.

Library Dependency Graph (Key Paths)#

The edges below are the implicitDependencies declared in each project.json. Reading this graph helps a new engineer understand which packages need to be understood first: @galatea/core and @galatea/firmware are the roots with no internal dependencies. Everything else builds up from there.

@galatea/core                  (no internal dependencies)

@galatea/firmware               (no internal dependencies)

@galatea/communication
  └── @galatea/core

@galatea/hardware-abstraction
  ├── @galatea/core
  ├── @galatea/communication
  └── @galatea/firmware

@galatea/kinematics
  ├── @galatea/core
  └── @galatea/hardware-abstraction

@galatea/locomotion
  ├── @galatea/core
  ├── @galatea/hardware-abstraction
  └── @galatea/kinematics

@galatea/whole-body-control
  ├── @galatea/core
  ├── @galatea/hardware-abstraction
  ├── @galatea/kinematics
  └── @galatea/locomotion

@galatea/choreography · @galatea/safety · @galatea/fleet · @galatea/sdk
  └── @galatea/core · @galatea/whole-body-control · @galatea/kinematics
      · @galatea/locomotion

@galatea/database
  └── @galatea/core · @galatea/whole-body-control · @galatea/kinematics
      · @galatea/locomotion

The TypeScript SDK additionally imports @galatea/analytics, @galatea/choreography, and @galatea/fleet directly (its package.json dependencies), composing their in-memory engines.

Dependencies on Other Oshun Domains#

Galatea currently has no cross-domain code dependencies. No @galatea/* package imports from another Oshun domain, and @galatea/* is not imported by any other domain in the codebase. Every package depends only on other @galatea/* packages and zod.

This boundary is intentional: Galatea is a self-contained robotics platform that other domains will integrate with, rather than one that is coupled to external Oshun business logic. Keeping the domain isolated means that changes to, for example, the commerce or content domains do not require re-testing the safety systems.

Cross-domain integrations described in product and phase planning — for example Aja motion capture, Shakti movement-quality metrics, or Neith digital-human primitives — are not yet implemented and are tracked as future work.

Build and Test Configuration#

All packages share the same build and test executors. When Nx is unavailable due to duplicate worktree projects, use the direct invocations below.

• Build executor: @nx/js:tsc
• Test executor: @nx/vite:test (Vitest)
• Tags: scope:galatea, type:lib, layer:domain
• Python client tag: type:sdk, lang:python

Direct invocations when Nx is unavailable:

# Type check a library
cd libs/galatea/<library> && npx tsc --noEmit

# Run tests
cd libs/galatea/<library> && npx vitest run

# Python client (tested separately, via uv)
cd libs/galatea/sdk/client-python && uv run --with pytest pytest tests/