# Uzume Developer Guide

> 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

```
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

```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';
```

4. 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"
      }
    }
  }
}
```

3. Add `implicitDependencies` for any Uzume libraries this new library depends
   on beyond core and nexus.

4. 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}
```

2. Add the crate to the workspace `Cargo.toml`:

```toml
[workspace]
members = [
  # ... existing crates
  "crates/uzume-{new-crate}",
]
```

3. Use workspace dependencies for shared crates:

```toml
# crates/uzume-{new-crate}/Cargo.toml
[dependencies]
serde = { workspace = true }
uzume-protocol-types = { path = "../uzume-protocol-types" }
```

4. 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.

---

## Related Documentation

- [Uzume Domain README](./README.md) - Domain overview, architecture, and
  library descriptions
- [Uzume Domain Proposal](../uzume-domain-proposal.md) - Full design document
- [CLAUDE.md](/CLAUDE.md) - Repository-wide development guidelines
