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#
# 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:
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#
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#
broadcast/ @uzume/broadcast Switcher, streaming, replay, simulcast (10 engines)
Video and Visual#
prism/ @uzume/prism Video and LED content management
aurora/ @uzume/aurora Extended reality and virtual production
previz/ @uzume/previz Pre-visualization and simulation
Audio#
sonos/ @uzume/sonos Audio engineering, routing, spatial
echo/ @uzume/echo Audience engagement and accessibility
Stage and Scenic#
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#
kinesis/ @uzume/kinesis Rigging hardware and motion control
Lighting and Effects#
lumina/ @uzume/lumina Lighting design and DMX/sACN control
pyra/ @uzume/pyra Special effects and pyrotechnics
Power and Infrastructure#
tesla/ @uzume/tesla Power distribution and monitoring
forge/ @uzume/forge Network infrastructure and IT ops
Communication and Logistics#
hermes/ @uzume/hermes Crew communication and intercom
atlas/ @uzume/atlas Production planning and logistics
chronos/ @uzume/chronos Scheduling and calendars
Safety and Compliance#
aegis/ @uzume/aegis Safety management and compliance
AI and Intelligence#
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:
@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#
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#
pnpm nx run-many --target=build --projects=tag:scope:uzume
Build the Rust/WASM Protocol Engines#
# 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:
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#
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#
pnpm nx run-many --target=test --projects=tag:scope:uzume
Run Rust Tests#
# 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)#
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:
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:
#[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#
# Lint a single library
pnpm nx lint @uzume/core
# Lint all Uzume libraries
pnpm nx run-many --target=lint --projects=tag:scope:uzume
Rust#
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:
- Create
libs/uzume/broadcast/src/virtual-camera-engine.ts - Create
libs/uzume/broadcast/src/virtual-camera-engine.spec.ts - Export from
libs/uzume/broadcast/src/index.ts:
export * from './virtual-camera-engine.js';
- Verify:
pnpm nx build @uzume/broadcast
pnpm nx test @uzume/broadcast
pnpm nx lint @uzume/broadcast
Adding a New Uzume TypeScript Library#
- Create directory structure under
libs/uzume/{new-lib}/ - Create
project.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"
}
}
}
}
-
Add
implicitDependenciesfor any Uzume libraries this new library depends on beyond core and nexus. -
Run
pnpm install.
Adding a New Rust Crate to Protocol Engines#
- Create the crate directory under
libs/uzume/protocol-engines/crates/:
cd libs/uzume/protocol-engines
cargo new --lib crates/uzume-{new-crate}
- Add the crate to the workspace
Cargo.toml:
[workspace]
members = [
# ... existing crates
"crates/uzume-{new-crate}",
]
- Use workspace dependencies for shared crates:
# crates/uzume-{new-crate}/Cargo.toml
[dependencies]
serde = { workspace = true }
uzume-protocol-types = { path = "../uzume-protocol-types" }
- Test:
cargo test -p uzume-{new-crate}
Running Database Migrations#
@uzume/core provides migration management targets:
# 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:
# 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:
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-enginebroadcast-multiviewer-management-enginereplay-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:
{
"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:
pnpm nx run-many --target=test --projects=tag:uzume:subsystem
Core Subpath Exports#
@uzume/core provides granular subpath exports:
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:
pnpm nx build @uzume/core
pnpm nx build @uzume/broadcast # Now has core available
Or let Nx resolve the order:
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:
# 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:
-
Missing target: Ensure
wasm32-unknown-unknownis installed:bashrustup target add wasm32-unknown-unknown -
wasm-pack not found: Install it:
bashcargo install wasm-pack -
Build optimization: The release profile uses
lto = trueandcodegen-units = 1for optimal WASM size. Debug builds are faster withopt-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:
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:
// 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:
# 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:
- Ensure PostgreSQL is running
- Verify the
DATABASE_URLenvironment variable - 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:
DATABASE_URL=postgresql://oshun:oshun_dev@localhost:5432/oshun_dev
NATS_URL=nats://localhost:4222
No environment variables are needed for other Uzume libraries.
Related Documentation#
- Uzume Domain README - Domain overview, architecture, and library descriptions
- Uzume Domain Proposal - Full design document
- CLAUDE.md - Repository-wide development guidelines