# 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. | Store | Rationale | | ----------------- | ----------------------------------------------------------------- | | `event-store` | Append-only for safety audit compliance; supports replay | | `telemetry-store` | Time-series optimized for high-frequency joint data (TimescaleDB) | | `garment-store` | Inventory with RFID tag index for sub-millisecond lookup | | `pose-store` | Versioned pose library with forward-compatibility requirements | | `show-store` | Show choreography with time-indexed cues for real-time execution | ### 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. | Loop | Frequency | Responsibilities | | --------------------- | --------- | ---------------------------------------------- | | Hardware control loop | 1 kHz | Joint torque/position commands, sensor reading | | Whole-body control | 500 Hz | WBC optimization, contact force resolution | | Locomotion | 200 Hz | Gait planning, balance, footstep selection | | Perception | 30–60 Hz | Camera processing, SLAM, person detection | | AI / behavior | 10–20 Hz | Behavioral engine decisions, LLM interaction | | Fleet telemetry | 1 Hz | State telemetry sent to cloud services | 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: ```bash # Type check a library cd libs/galatea/ && npx tsc --noEmit # Run tests cd libs/galatea/ && npx vitest run # Python client (tested separately, via uv) cd libs/galatea/sdk/client-python && uv run --with pytest pytest tests/ ```