# Uzume Domain

> **Uzume** - Live Entertainment and Media Production Platform

Uzume is a library-only domain providing comprehensive infrastructure for live
entertainment production, broadcast, and event management. Named after the
Japanese goddess of dawn, mirth, and revelry, the domain spans 26 libraries
covering every aspect of live production: broadcast switching and streaming,
lighting design, audio engineering, video and LED content, stage management,
scenic design, rigging and automation, crew communication, scheduling, safety
and compliance, network infrastructure, AI assistance, special effects, audience
engagement, extended reality, and pre-visualization.

The domain uniquely includes a **polyglot Rust crate workspace** within
`@uzume/protocol-engines` for performance-critical protocol implementations,
compiled to WASM for browser-side control surfaces.

See also the [Uzume Domain Proposal](../uzume-domain-proposal.md) for the full
design document.

---

## Architecture

```
                        @uzume/core
          (config, database, errors, event-bus, logging, utils)
         /       |       |       |       |       |        \
        /        |       |       |       |       |         \
  BROADCAST    VIDEO    AUDIO   STAGE   SCENIC  RIGGING   SAFETY
  broadcast    prism    sonos   koru    scena   kinesis   aegis
  nexus                 echo
  protocol-engines (Rust/WASM)
        |        |       |       |       |       |
  LIGHTING     FX      CREW    TIME    NETWORK  AI
  lumina       pyra    hermes  chronos  forge   muse
  aurora              atlas                    previz
  vestis                                      tesla
```

`@uzume/core` provides shared domain primitives (configuration contracts,
database migrations, error types, NATS event bus integration, logging, and
utility functions). All other libraries are domain-specific subsystems that can
operate independently but integrate through the core event bus.

---

## Libraries (26)

### Core Infrastructure

#### `@uzume/core` - Core Domain Framework

Shared domain primitives, configuration contracts, and platform utilities.

**Key exports:**

- `config/` - Configuration management and contracts
- `database/` - Drizzle ORM schema and migrations
- `errors/` - Domain-specific error hierarchy
- `event-bus/` - NATS-based event bus integration
- `logging/` - Structured logging
- `utils/` - Shared utility functions

**Dependencies:** `@oshun/database`, `@oshun/errors`, `@oshun/logging`, `nats`,
`drizzle-orm`, `zod`

#### `@uzume/nexus` - Show Control Protocol Bridge

Subsystem integration and protocol bridging for show control systems. Connects
disparate production systems through a unified control layer.

#### `@uzume/protocol-engines` - Rust Protocol Implementations

**Polyglot Rust/WASM workspace** containing performance-critical protocol
implementations. This is the only library in the domain that includes Rust code.

**Rust crates:**

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

**Build commands:**

```bash
# Run Rust tests
cargo test --workspace

# Build WASM control surface
wasm-pack build crates/uzume-control-surface-wasm --target web --release

# Run integration tests
cargo test -p uzume-integration-tests -- --nocapture
```

---

### Broadcast and Streaming

#### `@uzume/broadcast` - Broadcast Infrastructure

10 engines for broadcast switching, streaming, and multi-venue distribution.

| Engine                               | Description                               |
| ------------------------------------ | ----------------------------------------- |
| `broadcast-switcher-integration`     | Video switcher control integration        |
| `broadcast-multiviewer-management`   | Multi-viewer layout management            |
| `replay-system-integration`          | Replay and slow-motion system integration |
| `broadcast-graphics`                 | Real-time broadcast graphics overlay      |
| `broadcast-audio-split-management`   | Audio split and bus routing for broadcast |
| `broadcast-multi-platform-streaming` | Multi-platform simultaneous streaming     |
| `stream-health-monitoring-dashboard` | Real-time stream health monitoring        |
| `srt-contribution-feed-management`   | SRT protocol contribution feed management |
| `multi-venue-simulcast-distribution` | Multi-venue simulcast distribution        |
| `iso-recording-management`           | Isolated camera recording management      |

---

### Video and Visual

#### `@uzume/prism` - Video and LED Content Management

Video, projection mapping, and LED wall content management and playback.

#### `@uzume/aurora` - Extended Reality and Virtual Production

Extended reality (XR), interactive technology, and virtual production systems
including LED volume stages, camera tracking, and real-time compositing.

#### `@uzume/previz` - Pre-Visualization

Unified pre-visualization and simulation tooling for planning shows before
physical setup begins.

---

### Audio

#### `@uzume/sonos` - Audio Engineering

Audio engineering, routing, and spatial sound control for live venues and
broadcast. Handles mixing consoles, speaker arrays, and immersive audio.

#### `@uzume/echo` - Audience Engagement and Accessibility

Audience engagement, accessibility features, and in-show interactive
experiences. Includes live captioning, assistive listening, and audience
participation systems.

---

### Stage and Scenic

#### `@uzume/koru` - Stage Management

Stage management, cue calling, and rehearsal operations. The central nervous
system of live production, coordinating all departments during shows.

#### `@uzume/scena` - Scenic Design

Scenic design, construction planning, and props management workflows. Tracks
scenic elements from design through fabrication to load-in.

#### `@uzume/vestis` - Costume and Wardrobe

Costume design, wardrobe management, and quick-change coordination. Tracks
costume inventory, fitting schedules, and backstage quick-change sequences.

---

### Rigging and Automation

#### `@uzume/kinesis` - Rigging and Motion Control

Rigging hardware, automation, and motion-control coordination. Manages flying
systems, turntables, lifts, and automated scenery.

---

### Lighting and Effects

#### `@uzume/lumina` - Lighting Design

Lighting design and show control orchestration. DMX/sACN protocol support,
fixture libraries, and cue programming.

#### `@uzume/pyra` - Special Effects

Special effects, pyrotechnics, and atmospheric systems. Manages flame effects,
haze machines, confetti cannons, and CO2 jets with full safety interlocks.

---

### Power and Infrastructure

#### `@uzume/tesla` - Power Distribution

Power distribution, electrical planning, and monitoring. Load calculations,
generator management, and real-time power consumption tracking.

#### `@uzume/forge` - Network Infrastructure

Network infrastructure, observability, and IT operations for production
environments. Manages switches, wireless systems, and monitoring.

---

### Communication and Logistics

#### `@uzume/hermes` - Crew Communication

Crew communication and collaboration infrastructure including intercom systems,
messaging, and departmental coordination.

#### `@uzume/atlas` - Production Planning

Production planning, logistics, budgeting, and touring. Manages venue databases,
travel logistics, budgets, and production schedules.

#### `@uzume/chronos` - Scheduling

Scheduling, calendars, and timeline optimization. Handles rehearsal schedules,
load-in timelines, and crew availability.

---

### Safety and Compliance

#### `@uzume/aegis` - Safety and Compliance

Safety management, compliance tracking, risk analysis, and incident reporting.
Manages safety inspections, permits, and regulatory compliance.

---

### AI and Intelligence

#### `@uzume/muse` - AI Assistance

AI assistance, generative workflows, and show intelligence. Provides AI-powered
suggestions for lighting, audio, and set design.

---

## Technology Stack

| Layer                | Technology                               |
| -------------------- | ---------------------------------------- |
| Language (primary)   | TypeScript (ESM)                         |
| Language (protocols) | Rust (compiled to WASM + native)         |
| Build (TypeScript)   | `@nx/js:tsc`                             |
| Build (Rust)         | Cargo + wasm-pack                        |
| Database             | PostgreSQL via Drizzle ORM               |
| Event Bus            | NATS                                     |
| Validation           | Zod                                      |
| Testing              | Vitest (TypeScript), `cargo test` (Rust) |

---

## Configuration

**Project tags:** `["scope:uzume", "layer:domain", "type:lib"]`

**Build:** `@nx/js:tsc` for TypeScript libraries, with additional DB migration
and seeding targets for `@uzume/core`

**Note:** `@uzume/protocol-engines` uses Cargo for Rust compilation and
wasm-pack for WASM builds. These are integrated into the Nx build graph via
`nx:run-commands` executor.

---

## Development

```bash
# Run TypeScript tests for a library
pnpm nx test @uzume/core
pnpm nx test @uzume/broadcast

# Build a library
pnpm nx build @uzume/core

# Run all uzume tests
pnpm nx run-many --target=test --projects=tag:scope:uzume

# Build all uzume libraries
pnpm nx run-many --target=build --projects=tag:scope:uzume

# Rust protocol engines
cd libs/uzume/protocol-engines
cargo test --workspace
cargo check --workspace

# Build WASM control surface
cd libs/uzume/protocol-engines
wasm-pack build crates/uzume-control-surface-wasm --target web --release
```

---

## Related Domains

- **Yemaya** - Creative Studio domain that may use Uzume for live production
  tooling
- **Iris** - Voice domain that may integrate with Uzume audio systems
- **Hathor** - Worldbuilding domain for narrative-driven live experiences
