Eve library

Uzume Developer Guide

Guide

Revision 1

On this page

Comprehensive development guide for the Uzume (Live Entertainment) domain libraries.

This guide covers local development setup, building, testing, debugging, and common development tasks for all 22 TypeScript libraries and the Rust/WASM protocol-engines workspace.


Prerequisites#

Required Software#

Tool Version Purpose
Node.js >= 20.0 JavaScript runtime
pnpm >= 10.0 Package manager
Nx (via pnpm) Monorepo task runner
PostgreSQL 15+ Required for @uzume/core database development

Required for Rust/WASM Development (@uzume/protocol-engines only)#

Tool Version Purpose
Rust toolchain stable Rust compiler (managed via rust-toolchain.toml)
wasm-pack latest WASM build tool
cargo (via Rust) Rust package manager

The rust-toolchain.toml in libs/uzume/protocol-engines/ specifies the stable channel with rustfmt, clippy components and the wasm32-unknown-unknown target.

Installation#

bash
# From the repository root
pnpm install

# For Rust development, ensure toolchain is installed:
rustup show  # Verify Rust toolchain

Database Setup (for @uzume/core)#

@uzume/core includes Drizzle ORM schema and database migrations. Start the development PostgreSQL instance:

bash
docker compose -f docker/docker-compose.dev.yml up -d

# Connection: postgresql://oshun:oshun_dev@localhost:5432/oshun_dev

For all other Uzume libraries (broadcast, lumina, sonos, etc.), no database or external services are required for development and testing.


Project Structure#

Uzume is the largest library-only domain with 22 TypeScript libraries plus 1 Rust/WASM workspace. All live under libs/uzume/:

Core Infrastructure#

text
core/              @uzume/core              Config, database, errors, event-bus, logging
nexus/             @uzume/nexus             Show control protocol bridge
protocol-engines/  uzume-protocol-engines   Rust/WASM protocol implementations

Broadcast and Streaming#

text
broadcast/         @uzume/broadcast         Switcher, streaming, replay, simulcast (10 engines)

Video and Visual#

text
prism/             @uzume/prism             Video and LED content management
aurora/            @uzume/aurora            Extended reality and virtual production
previz/            @uzume/previz            Pre-visualization and simulation

Audio#

text
sonos/             @uzume/sonos             Audio engineering, routing, spatial
echo/              @uzume/echo              Audience engagement and accessibility

Stage and Scenic#

text
koru/              @uzume/koru              Stage management and cue calling
scena/             @uzume/scena             Scenic design and construction
vestis/            @uzume/vestis            Costume and wardrobe management

Rigging and Automation#

text
kinesis/           @uzume/kinesis           Rigging hardware and motion control

Lighting and Effects#

text
lumina/            @uzume/lumina            Lighting design and DMX/sACN control
pyra/              @uzume/pyra              Special effects and pyrotechnics

Power and Infrastructure#

text
tesla/             @uzume/tesla             Power distribution and monitoring
forge/             @uzume/forge             Network infrastructure and IT ops

Communication and Logistics#

text
hermes/            @uzume/hermes            Crew communication and intercom
atlas/             @uzume/atlas             Production planning and logistics
chronos/           @uzume/chronos           Scheduling and calendars

Safety and Compliance#

text
aegis/             @uzume/aegis             Safety management and compliance

AI and Intelligence#

text
muse/              @uzume/muse             AI assistance and generative workflows

Implicit Dependency Structure#

Most subsystem libraries declare implicitDependencies on @uzume/core and @uzume/nexus, meaning Nx builds core and nexus first. Some have additional dependencies:

text
@uzume/core  (foundation: config, database, event-bus, logging, errors)
  |
  +-- @uzume/nexus  (show control bridge)
  |     |
  |     +-- @uzume/broadcast  (depends: core, nexus)
  |     +-- @uzume/lumina     (depends: core, nexus)
  |     +-- @uzume/sonos      (depends: core, nexus)
  |     +-- @uzume/koru       (depends: core, nexus)
  |     +-- ...all other subsystems (depend: core, nexus)
  |
  +-- @uzume/kinesis (depends: core, nexus, lumina)
  |
  +-- uzume-protocol-engines  (standalone Rust workspace)

Building Libraries#

Build a Single TypeScript Library#

bash
pnpm nx build @uzume/core
pnpm nx build @uzume/broadcast
pnpm nx build @uzume/lumina
pnpm nx build @uzume/sonos

Build All Uzume TypeScript Libraries#

bash
pnpm nx run-many --target=build --projects=tag:scope:uzume

Build the Rust/WASM Protocol Engines#

bash
# Check Rust compilation
pnpm nx check uzume-protocol-engines

# Run Rust tests
pnpm nx test uzume-protocol-engines

# Run integration tests
pnpm nx test:integration uzume-protocol-engines

# Build WASM control surface
pnpm nx build:wasm uzume-protocol-engines

Or directly with Cargo:

bash
cd libs/uzume/protocol-engines
cargo check --workspace
cargo test --workspace
wasm-pack build crates/uzume-control-surface-wasm --target web --release

Build Configuration#

TypeScript libraries use @nx/js:tsc:

Setting Value
Executor @nx/js:tsc
Output dist/libs/uzume/{library}/
Module format ESM ("type": "module")

@uzume/core has additional Nx targets:

Target Command
db:migrate tsx libs/uzume/core/src/database/migrations/cli.ts up
db:migrate:down tsx libs/uzume/core/src/database/migrations/cli.ts down
db:migrate:status tsx libs/uzume/core/src/database/migrations/cli.ts status
db:seed:preview tsx libs/uzume/core/src/database/seeds/cli.ts

uzume-protocol-engines uses Cargo/wasm-pack via nx:run-commands:

Target Command
check cargo check --workspace
test cargo test --workspace
test:integration cargo test -p uzume-integration-tests
build:wasm scripts/build-web.sh (wasm-pack build)

Testing#

Run Tests for a Single TypeScript Library#

bash
pnpm nx test @uzume/core
pnpm nx test @uzume/broadcast
pnpm nx test @uzume/lumina
pnpm nx test @uzume/kinesis

Run All Uzume TypeScript Tests#

bash
pnpm nx run-many --target=test --projects=tag:scope:uzume

Run Rust Tests#

bash
# All crates
pnpm nx test uzume-protocol-engines

# Or directly:
cd libs/uzume/protocol-engines
cargo test --workspace

# Integration tests only (with output)
cargo test -p uzume-integration-tests -- --nocapture

Test Configuration (TypeScript)#

typescript
import { defineConfig } from 'vitest/config';

export default defineConfig({
  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'],
    },
  },
});

Note: Uzume's coverage config uses lcov reporter (in addition to text and html), which can be consumed by CI coverage tools.

Test Count#

The domain has 370 TypeScript test files across 22 libraries, plus Rust tests in the protocol-engines workspace. This is the most extensively tested domain in the monorepo.

Writing TypeScript Tests#

Uzume tests often verify engine configurations and event handling:

typescript
import { describe, it, expect, vi } from 'vitest';
import {
  createBroadcastSwitcherEngine,
  BroadcastSwitcherConfig,
} from './broadcast-switcher-integration-engine.js';

describe('BroadcastSwitcherEngine', () => {
  it('should create a switcher engine with default config', () => {
    const engine = createBroadcastSwitcherEngine({
      mixEffectBlocks: 2,
      auxOutputs: 6,
    });
    expect(engine).toBeDefined();
    expect(engine.config.mixEffectBlocks).toBe(2);
  });

  it('should handle input source switching', async () => {
    const engine = createBroadcastSwitcherEngine(config);
    const result = await engine.switchInput({
      meBlock: 0,
      source: 'camera-1',
      transition: 'cut',
    });
    expect(result.activeSource).toBe('camera-1');
  });
});

Writing Rust Tests#

Rust tests live alongside the implementation in src/lib.rs or in dedicated test modules:

rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_timing_precision() {
        let timer = TimingEngine::new(TimingConfig {
            frame_rate: FrameRate::Fps30,
            timecode_format: TimecodeFormat::Smpte,
        });
        let tc = timer.frames_to_timecode(900);
        assert_eq!(tc.to_string(), "00:00:30:00");
    }
}

Linting#

TypeScript#

bash
# Lint a single library
pnpm nx lint @uzume/core

# Lint all Uzume libraries
pnpm nx run-many --target=lint --projects=tag:scope:uzume

Rust#

bash
cd libs/uzume/protocol-engines
cargo clippy --workspace -- -D warnings
cargo fmt --all -- --check

Common Development Tasks#

Adding a New Engine to an Existing Library#

For example, adding a new virtual-camera-engine to @uzume/broadcast:

  1. Create libs/uzume/broadcast/src/virtual-camera-engine.ts
  2. Create libs/uzume/broadcast/src/virtual-camera-engine.spec.ts
  3. Export from libs/uzume/broadcast/src/index.ts:
typescript
export * from './virtual-camera-engine.js';
  1. Verify:
bash
pnpm nx build @uzume/broadcast
pnpm nx test @uzume/broadcast
pnpm nx lint @uzume/broadcast

Adding a New Uzume TypeScript Library#

  1. Create directory structure under libs/uzume/{new-lib}/
  2. Create project.json:
json
{
  "name": "@uzume/{new-lib}",
  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
  "sourceRoot": "libs/uzume/{new-lib}/src",
  "projectType": "library",
  "tags": ["scope:uzume", "type:lib", "layer:domain", "uzume:subsystem"],
  "implicitDependencies": ["@uzume/core", "@uzume/nexus"],
  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/libs/uzume/{new-lib}",
        "main": "libs/uzume/{new-lib}/src/index.ts",
        "tsConfig": "libs/uzume/{new-lib}/tsconfig.lib.json",
        "assets": []
      }
    },
    "lint": {
      "executor": "@nx/eslint:lint",
      "outputs": ["{options.outputFile}"],
      "options": {
        "lintFilePatterns": ["libs/uzume/{new-lib}/**/*.ts"]
      }
    },
    "test": {
      "executor": "@nx/vite:test",
      "outputs": ["{workspaceRoot}/coverage/libs/uzume/{new-lib}"],
      "options": {
        "config": "libs/uzume/{new-lib}/vitest.config.ts"
      }
    }
  }
}
  1. Add implicitDependencies for any Uzume libraries this new library depends on beyond core and nexus.

  2. Run pnpm install.

Adding a New Rust Crate to Protocol Engines#

  1. Create the crate directory under libs/uzume/protocol-engines/crates/:
bash
cd libs/uzume/protocol-engines
cargo new --lib crates/uzume-{new-crate}
  1. Add the crate to the workspace Cargo.toml:
toml
[workspace]
members = [
  # ... existing crates
  "crates/uzume-{new-crate}",
]
  1. Use workspace dependencies for shared crates:
toml
# crates/uzume-{new-crate}/Cargo.toml
[dependencies]
serde = { workspace = true }
uzume-protocol-types = { path = "../uzume-protocol-types" }
  1. Test:
bash
cargo test -p uzume-{new-crate}

Running Database Migrations#

@uzume/core provides migration management targets:

bash
# Run pending migrations
pnpm nx db:migrate @uzume/core

# Check migration status
pnpm nx db:migrate:status @uzume/core

# Roll back the latest migration
pnpm nx db:migrate:down @uzume/core

# Preview seed data
pnpm nx db:seed:preview @uzume/core

Working with the NATS Event Bus#

@uzume/core integrates with NATS for inter-service event communication. To develop against the event bus, start a local NATS server:

bash
# NATS can be started via Docker
docker run -p 4222:4222 nats:latest

The event bus module in @uzume/core provides typed event publishing and subscription.


Key Patterns and Conventions#

Library Metadata Export#

Every Uzume library exports a metadata object as its first export:

typescript
export interface UzumeBroadcastLibraryMetadata {
  readonly id: '@uzume/broadcast';
  readonly subsystem: string;
  readonly description: string;
}

export const UZUME_BROADCAST_METADATA: UzumeBroadcastLibraryMetadata = {
  id: '@uzume/broadcast',
  subsystem: 'broadcast',
  description: 'Broadcast switching, streaming, replay, and simulcast control',
};

Follow this pattern when creating new libraries. The metadata supports runtime discovery and service registration.

Engine Pattern#

Subsystem libraries organize functionality into "engines" - self-contained modules that handle a specific production concern. For example, @uzume/broadcast has 10 engines:

  • broadcast-switcher-integration-engine
  • broadcast-multiviewer-management-engine
  • replay-system-integration-engine
  • etc.

Each engine exports its types, factory functions, and configuration. Name new engines with the -engine suffix.

Implicit Dependencies#

Uzume uses Nx implicitDependencies rather than npm package dependencies for inter-library relationships. This tells Nx about the build order without requiring actual import resolution:

json
{
  "implicitDependencies": ["@uzume/core", "@uzume/nexus"]
}

Subsystem Tags#

In addition to the standard scope:uzume tag, subsystem libraries include uzume:subsystem to distinguish them from core infrastructure. Use this tag for running commands against only subsystem libraries:

bash
pnpm nx run-many --target=test --projects=tag:uzume:subsystem

Core Subpath Exports#

@uzume/core provides granular subpath exports:

typescript
import {} from /* ... */ '@uzume/core'; // Full API
import {} from /* ... */ '@uzume/core/config'; // Config only
import {} from /* ... */ '@uzume/core/database'; // Database only
import {} from /* ... */ '@uzume/core/errors'; // Errors only
import {} from /* ... */ '@uzume/core/event-bus'; // Event bus only
import {} from /* ... */ '@uzume/core/logging'; // Logging only

Rust Crate Organization#

The protocol-engines Rust workspace follows a layered structure:

Crate Layer Purpose
uzume-protocol-types Types Shared protocol type definitions
uzume-timing-core Core High-precision timing engine
uzume-network-io Infrastructure Low-level network I/O
uzume-node-bridge Bridge Node.js native bridge (napi-rs)
uzume-control-surface-wasm Bridge Browser WASM control surface
uzume-integration-tests Testing Cross-crate integration tests

Key workspace-level dependencies: serde, tokio, wasm-bindgen, napi, napi-derive, bytes, thiserror.


Debugging Tips#

Build Order with Implicit Dependencies#

If a build fails because core types are not available, ensure @uzume/core is built first:

bash
pnpm nx build @uzume/core
pnpm nx build @uzume/broadcast  # Now has core available

Or let Nx resolve the order:

bash
pnpm nx run-many --target=build --projects=tag:scope:uzume

NATS Event Bus Connection#

If event bus tests fail with connection errors, verify NATS is running:

bash
# Check if NATS is accessible
nc -z localhost 4222 && echo "NATS is running" || echo "NATS is not running"

For unit tests, mock the NATS connection rather than requiring a live server.

Rust WASM Build Failures#

Common issues with wasm-pack build:

  1. Missing target: Ensure wasm32-unknown-unknown is installed:

    bash
    rustup target add wasm32-unknown-unknown
    
  2. wasm-pack not found: Install it:

    bash
    cargo install wasm-pack
    
  3. Build optimization: The release profile uses lto = true and codegen-units = 1 for optimal WASM size. Debug builds are faster with opt-level = 1.

Rust napi-rs Node Bridge#

The uzume-node-bridge crate uses napi-rs to create Node.js native modules. To build and test the native bridge:

bash
cd libs/uzume/protocol-engines/crates/uzume-node-bridge
cargo build

napi-rs requires Node.js headers at compile time. Ensure napi version 2.16 with napi8 feature flag is used (as specified in workspace dependencies).

TypeScript Import Paths#

ESM requires .js extensions in imports:

typescript
// Correct
import { BroadcastConfig } from './broadcast-switcher-integration-engine.js';

// Incorrect
import { BroadcastConfig } from './broadcast-switcher-integration-engine';

Large Test Suite Management#

With 370 test files, running all tests can be slow. Target specific libraries or modules during development:

bash
# Single library
pnpm nx test @uzume/broadcast

# Specific test file pattern
pnpm nx test @uzume/broadcast -- --testPathPattern="switcher"

Database Migration Issues#

If migration targets fail:

  1. Ensure PostgreSQL is running
  2. Verify the DATABASE_URL environment variable
  3. Check migration status:
    bash
    pnpm nx db:migrate:status @uzume/core
    

Project Configuration Reference#

Tags#

Tag Libraries
scope:uzume All Uzume libraries
type:lib All TypeScript libraries
type:rust uzume-protocol-engines only
layer:domain All TypeScript subsystem libraries
layer:infrastructure uzume-protocol-engines
uzume:core @uzume/core only
uzume:subsystem All subsystem libraries (not core)

Executors#

Target Executor (TypeScript) Executor (Rust)
build @nx/js:tsc N/A
check N/A cargo check
test @nx/vite:test cargo test
test:integration N/A cargo test
build:wasm N/A wasm-pack build
lint @nx/eslint:lint cargo clippy
db:migrate nx:run-commands N/A

Core Dependencies#

Dependency Used By Purpose
@oshun/database @uzume/core Shared database utilities
@oshun/errors @uzume/core Shared error types
@oshun/logging @uzume/core Shared logging
nats @uzume/core Event bus
drizzle-orm @uzume/core Database ORM
zod @uzume/core Validation
tsx @uzume/core TypeScript execution (migrations)

Environment Variables#

For @uzume/core database and event bus development:

bash
DATABASE_URL=postgresql://oshun:oshun_dev@localhost:5432/oshun_dev
NATS_URL=nats://localhost:4222

No environment variables are needed for other Uzume libraries.