# Uzume — Systems Deep Dive

> The `libs/uzume/` area: a live-event / show-control platform built as one core
> foundation library, a protocol-bridging library, a Rust low-latency protocol
> workspace, and ~19 domain "subsystem" libraries — each owning one department
> of a working production (lighting, audio, video, rigging, pyro, scenic,
> costume, safety, broadcast, and more).

## What this area is

Uzume is the monorepo's **live-entertainment production** domain: the software a
touring show, theatre, or arena uses to plan, rehearse, and run a performance.
The directory is not one package but **22 separate Nx projects**. They split
into three tiers by tag: a single `uzume:core` foundation (`@uzume/core`), a
single `uzume:protocol` bridge (`@uzume/nexus`), a Rust `type:rust` /
`layer:infrastructure` workspace (`uzume-protocol-engines`), and the rest tagged
`layer:domain` / `uzume:subsystem` — the per-department engine libraries.

Every node above the foundation declares its dependencies in `project.json` via
`implicitDependencies`. `@uzume/core` has none — it is the root of the graph.
`@uzume/nexus` depends on `@uzume/core`. Every domain subsystem declares
`["@uzume/core", "@uzume/nexus"]`, and `@uzume/kinesis` additionally depends on
`@uzume/lumina` (rigging coordinates with lighting). This gives the area a clean
spine: shared primitives and protocol types live in `core`, live-show protocol
I/O bridges through `nexus`, and each subsystem composes those rather than
re-declaring them.

The implementations are real and substantial, not scaffolds. The TypeScript
libraries total well over 250K lines of domain logic across ~430 engine modules
(for example `libs/uzume/aegis/src` is ~27K LOC across 31 engines,
`libs/uzume/kinesis/src` ~27.5K across 30, `libs/uzume/core/src` ~12K of impl).
Each engine module follows a consistent shape — a `*-engine.ts` exporting a
typed engine class plus its input/output interfaces, paired with a `*.spec.ts` —
and the barrel `src/index.ts` re-exports the public surface alongside a
`UZUME_<NAME>_METADATA` descriptor. The code is genuinely domain-specific:
`libs/uzume/core/src/utils/smpte-timecode.ts` implements SMPTE drop-frame math
with the real `FRAMES_PER_10_MINUTES_DF = 17_982` constant,
`safety-calculations.ts` uses `GRAVITY_MPS2 = 9.80665` and
pounds-per-square-foot to Pascal conversion, and
`libs/uzume/kinesis/src/bridle-calculator-engine.ts` computes 3D leg-tension
vectors with per-hardware SWL utilization.

## How it fits the wider system

The foundation (`@uzume/core`) owns the wire types every subsystem speaks: DMX,
Art-Net/sACN, OSC/MIDI/timecode, GDTF/MVR, plus show/venue/cue/department domain
models, a NATS-backed event bus, a migration-driven Postgres schema, and an
error framework with safety escalation. `@uzume/nexus` consumes those types
(e.g. `dmx-protocol-engines.ts` imports `DMX_CHANNEL_COUNT`, Art-Net/sACN/RDM
parsers from `@uzume/core/types`) and exposes the show-control bridging engines.
The domain subsystems then compose `core` + `nexus` to deliver department
features. The `uzume-protocol-engines` Rust workspace sits underneath as the
low-latency execution layer, exposing typed Node.js bindings (napi-rs) and a
browser control-surface bridge (wasm-bindgen) for the timing-sensitive output
paths the TypeScript engines orchestrate. Walk the dependency edges on any node
below to see exactly who composes it.

## Entity reference

### @uzume/core

The foundation library (`libs/uzume/core/src`), tagged `uzume:core` with **no**
upstream dependency — the root of the area's graph. Its barrel re-exports six
subsystems: `config` (Zod-validated env contracts), `database` (a
migration/schema/seed stack under `database/migrations` and `database/seeds`),
`errors` (`error-codes`, `error-framework`, `error-routing`,
`safety-escalation`, `uzume-error`), `event-bus` (an in-memory transport plus
`uzume-nats-event-bus`), `logging` (`uzume-logger`), and `utils`. It also
carries the shared `types/` tree — `cue`, `department`, `show`, `timeline`,
`venue`, and the `protocol-*` models (`protocol-dmx`, `protocol-gdtf`,
`protocol-mvr`, `protocol-audio`, `protocol-video`,
`protocol-automation-safety`, etc.) — and the engineering utilities
(`smpte-timecode`, `safety-calculations`, `dmx`, `protocol-address`,
`unit-conversion`). Every other Uzume library is built on these primitives.

### @uzume/nexus

The show-control protocol bridge (`libs/uzume/nexus/src`), tagged
`uzume:protocol` and depending only on `@uzume/core`. Its metadata describes it
as "Show control protocol bridging and subsystem integration." Four engine
modules make up the surface: `dmx-protocol-engines` (DMX512 / Art-Net 4 / sACN
universe management with per-channel dirty-tracking and refresh batching, built
on the DMX parsers from `@uzume/core/types`), `osc-midi-timecode-engines`,
`device-management-engines`, and `show-control-engines`. Every domain subsystem
lists `@uzume/nexus` as an implicit dependency, making it the integration seam
between the core types and the department engines.

### uzume-protocol-engines

The Rust workspace (`libs/uzume/protocol-engines`), tagged `type:rust` /
`layer:infrastructure`, providing the low-latency execution foundation. Its
`Cargo.toml` defines a six-crate workspace built and tested through Nx
`nx:run-commands` targets (`cargo check/test --workspace`):
`uzume-protocol-types` (~3.1K LOC of shared
`DMXUniverse`/`MIDIMessage`/`OSCMessage`/`TimecodeFrame` models),
`uzume-timing-core` (~10K LOC — high-precision `Instant`-anchored clock,
timer-wheel scheduler, and SMPTE/LTC/MTC frame counters), `uzume-network-io`
(~3.7K LOC of Tokio UDP/TCP for Art-Net/sACN/OSC with multicast helpers),
`uzume-node-bridge` (a napi-rs native bridge), `uzume-control-surface-wasm` (a
`wasm-bindgen` web bridge built via `wasm-pack --target web`), and
`uzume-integration-tests` (a ~570-line loopback/latency suite). These are real
implementations, not skeletons; the README documents the crate roles and build
commands.

### @uzume/aegis

Safety, compliance, risk analysis, and incident tracking
(`libs/uzume/aegis/src`) — ~27K LOC across 31 engines. It covers regulatory
modules (`osha-compliance-module-engine`, `nfpa-compliance-module-engine`,
`ansi-esta-compliance-tracking-engine`,
`european-safety-standards-module-engine`,
`jurisdiction-specific-compliance-engine`), crowd safety
(`crowd-safety-modeling-engine`, `emergency-evacuation-simulation-engine`,
`crowd-density-monitoring-integration-engine`,
`crowd-barrier-layout-designer-engine`), environmental interlocks
(`wind-speed-monitoring-interlock-engine`, `heat-stress-monitoring-engine`,
`weather-triggered-show-modification-engine`), and incident workflow
(`risk-assessment-engine`, `root-cause-analysis-framework-engine`,
`structured-incident-reporting-system-engine`,
`anonymous-near-miss-reporting-system-engine`, `safety-audit-trail-engine`).

### @uzume/atlas

Production planning, logistics, budgeting, and touring (`libs/uzume/atlas/src`)
— ~24K LOC across 25 engines. It spans finance (`production-budget-engine`,
`purchase-order-system-engine`, `financial-settlement-reconciliation-engine`,
`expense-tracking-per-diem-management-engine`), crew
(`crew-database-profile-management-engine`, `crew-scheduling-engine`,
`crew-call-sheet-generator-engine`, `time-tracking-payroll-engine`,
`crew-skills-certification-compliance-engine`), equipment lifecycle
(`equipment-inventory-management-engine`,
`maintenance-scheduling-tracking-engine`,
`cross-rental-sub-rental-management-engine`,
`equipment-depreciation-lifecycle-management-engine`), touring logistics
(`tour-routing-engine`, `venue-advance-system-engine`,
`freight-shipping-management-engine`, `accommodation-travel-management-engine`),
and sustainability (`carbon-footprint-calculator-engine`,
`green-rider-sustainability-policy-management-engine`).

### @uzume/aurora

Extended reality, interactive tech, and virtual production
(`libs/uzume/aurora/src`) — ~22K LOC across 26 engines. It covers virtual
production (`disguise-xr-stage-management-engine`,
`unreal-engine-live-control-integration-engine`,
`virtual-production-color-science-pipeline-engine`,
`camera-tracking-data-distribution-engine`,
`virtual-set-extension-visualization-engine`), drones and displays
(`drone-show-design-engine`, `drone-pyrotechnic-coordination-engine`,
`holographic-display-management-engine`,
`high-resolution-led-display-management-engine`), real-time location systems
(`rtls-position-visualization-engine`, `rtls-emergency-mustering-system-engine`,
`uwb-indoor-positioning-system-integration-engine`), digital twins
(`realtime-digital-twin-engine`, `digital-twin-what-if-simulation-engine`,
`ai-anomaly-detection-engine`), and mocap/wearables
(`motion-capture-session-management-engine`,
`physical-digital-lighting-alignment-system-engine`,
`wearable-technology-integration-engine`).

### @uzume/broadcast

Broadcast switching, streaming, replay, and simulcast control
(`libs/uzume/broadcast/src`) — ~4.3K LOC across 10 engines:
`broadcast-switcher-integration-engine`,
`broadcast-multiviewer-management-engine`, `replay-system-integration-engine`,
`broadcast-graphics-engine`, `broadcast-audio-split-management-engine`,
`broadcast-multi-platform-streaming-engine`,
`stream-health-monitoring-dashboard-engine`,
`srt-contribution-feed-management-engine`,
`multi-venue-simulcast-distribution-engine`, and
`iso-recording-management-engine`. It is the smallest of the domain subsystems
by line count but follows the same engine-per-module shape as its siblings.

### @uzume/chronos

Scheduling, calendars, and timeline optimization (`libs/uzume/chronos/src`) —
~9.6K LOC across 10 engines: `master-production-timeline-engine`,
`rehearsal-scheduling-engine`, `tech-rehearsal-scheduling-template-engine`,
`multi-venue-production-calendar-engine`,
`deadline-tracking-notification-engine`, `tour-routing-optimization-engine`,
`resource-leveling-engine`, `schedule-disruption-what-if-engine`,
`calendar-synchronization-engine`, and `automated-scheduling-reporting-engine`.
It is the time/calendar planning layer that the operational subsystems schedule
against.

### @uzume/echo

Audience engagement, accessibility, and in-show interaction
(`libs/uzume/echo/src`) — ~21.5K LOC across 21 engines. Engagement features
include `beacon-ble-proximity-system-engine`,
`audience-response-polling-system-engine`, `ar-overlay-mobile-feature-engine`,
`led-wristband-control-engine`, `crowd-analytics-engine`, and
`white-label-audience-mobile-app-platform-engine`. A large accessibility cluster
covers `comprehensive-accessibility-system-engine`,
`assistive-listening-system-integration-engine`,
`audio-description-management-system-engine` (with Dante/AES67 routing types),
`sign-language-interpreter-integration-engine`,
`surtitle-supertitle-management-system-engine`,
`relaxed-sensory-friendly-performance-mode-engine`,
`comprehensive-haptic-tactile-feedback-system-engine`, and
`audience-biometric-and-emotion-sensing-engine`. The barrel uses explicit named
re-exports for several engines to disambiguate overlapping type names.

### @uzume/forge

Network infrastructure, observability, and IT operations
(`libs/uzume/forge/src`) — ~7.7K LOC across 10 engines:
`network-topology-designer-engine`,
`entertainment-network-vlan-template-library-engine`,
`switch-configuration-management-engine`, `ip-address-management-engine`,
`ptp-grandmaster-clock-management-engine`,
`network-bandwidth-monitoring-engine`, `multicast-traffic-management-engine`,
`production-wifi-planning-engine`, `network-security-management-engine`, and
`cable-and-fiber-documentation-system-engine`. It is the IT/networking backbone
that the AV-over-IP subsystems (Dante audio, video routing, sACN lighting)
depend on operationally.

### @uzume/hermes

Crew communication and collaboration infrastructure (`libs/uzume/hermes/src`) —
~7.4K LOC across 10 engines: `production-messaging-system-engine`,
`intercom-monitoring-interface-engine`, `video-monitoring-system-engine`,
`god-mic-paging-system-integration-engine`,
`production-contacts-database-engine`,
`centralized-document-management-system-engine`,
`crew-mobile-app-platform-engine`,
`digital-call-board-system-integration-engine`,
`guest-visitor-management-engine`, and `real-time-translation-service-engine`.
It is the people-facing comms layer of the production.

### @uzume/kinesis

Rigging, automation, and motion-control coordination (`libs/uzume/kinesis/src`)
— ~27.5K LOC across 30 engines, and the one subsystem that additionally depends
on `@uzume/lumina`. It covers fly and hoist systems
(`chain-hoist-management-engine`, `counterweight-fly-system-tracking-engine`,
`motorized-fly-system-control-engine`), performer flying
(`performer-flying-system-control-engine`,
`performer-flying-safety-system-engine`,
`track-and-trolley-flying-system-control-engine`), load engineering
(`load-monitoring-dashboard-engine`, `structural-load-budget-calculator-engine`,
`bridle-calculator-engine` — real 3D leg-tension vector math with per-hardware
SWL utilization), robotics and kinetics
(`industrial-robot-arm-control-integration-engine`,
`robot-choreography-timeline-editor-engine`,
`robot-safety-zone-management-engine`, `kinetic-winch-system-control-engine`,
`kinetic-anti-collision-system-engine`), animatronics, and stage machinery
(`turntable-revolve-control-engine`, `stage-lift-trap-control-engine`,
`kabuki-drop-system-management-engine`, `rain-curtain-water-effect-engine`).

### @uzume/koru

Stage management, cue calling, and rehearsal operations (`libs/uzume/koru/src`)
— ~8.8K LOC across 15 engines: `digital-cue-sheet-engine`,
`show-calling-interface-engine`, `cue-light-station-system-engine`,
`multi-department-cue-status-dashboard-engine`,
`hold-emergency-stop-protocol-engine`,
`rehearsal-note-management-system-engine`, `show-report-generator-engine`,
`digital-blocking-notation-system-engine`, `preset-checklist-system-engine`,
`understudy-swing-tracking-system-engine`, `intercom-integration-engine`,
`run-sheet-production-schedule-engine`, `scene-change-management-system-engine`,
`digital-call-board-system-engine`, and `multi-language-interface-engine`. This
is the stage manager's "calling the show" toolkit that drives the department
subsystems on cue.

### @uzume/lumina

Lighting design and show control orchestration (`libs/uzume/lumina/src`) — ~9.5K
LOC across 21 engines, and a dependency of `@uzume/kinesis`. It implements the
lighting pipeline end to end: fixture data (`gdtf-parser`,
`mvr-exchange-engine`, `fixture-library-manager`, `fixture-patch-engine`,
`fixture-parameter-engine`), color science (`color-engine`, `gel-library`,
`color-picker-engine`, `color-consistency-engine`, `subtractive-mixing-engine`),
cueing and playback (`tracking-cue-stack-engine`, `fade-engine`,
`cue-trigger-engine`, `multi-cue-list-playback-engine`, `cue-macro-engine`), and
content/effects (`parametric-effects-engine`, `pixel-mapping-engine`,
`generative-content-engine`, `atmospheric-effects-engine`), bridged to hardware
via `console-integration-bridge`.

### @uzume/muse

AI assistance, generative workflows, and show intelligence
(`libs/uzume/muse/src`) — ~13.4K LOC across 16 engines spanning musical
intelligence (`musical-analysis-engine`, `bpm-synchronization-engine`,
`show-energy-arc-analyzer-engine`, `ai-powered-cue-placement-engine`),
generative content (`ai-generative-visual-content-engine`,
`ai-color-palette-generator-engine`, `ai-effect-choreography-engine`,
`lyric-to-visual-suggestion-engine`), natural-language and voice control
(`natural-language-show-programming-interface-engine`,
`voice-activated-show-control-engine`), and operational ML
(`ai-powered-anomaly-detection-engine`, `predictive-maintenance-engine`,
`ml-driven-budget-forecasting-engine`, `ai-crew-scheduling-optimization-engine`,
`ai-automated-documentation-generator-engine`). The barrel exposes adapter seam
types such as `LyricNlpAnalyzerAdapter` and `SpeechToTextAdapter`, i.e. model
integration is structured as injectable adapters rather than hardcoded calls.

### @uzume/previz

Unified pre-visualization and simulation tooling (`libs/uzume/previz/src`) —
~15K LOC across 15 engines: rendering (`fixture-rendering-engine`,
`led-wall-projection-surface-rendering-engine`, `venue-3d-rendering-engine`,
`visual-effects-simulation-rendering-engine`,
`scenic-automation-visualization-engine`, `rendering-quality-modes-engine`),
review and capture (`unified-department-timeline-scrubbing-engine`,
`vr-walkthrough-webxr-engine`, `multi-camera-virtual-preview-engine`,
`screenshot-video-capture-engine`, `audio-spatialization-preview-engine`),
collaboration (`collaborative-multi-user-previz-session-engine`,
`live-console-connection-previz-engine`), plus
`previz-tool-interoperability-engine` and
`performance-benchmarking-optimization-engine`. It is the cross-department
visual rehearsal layer.

### @uzume/prism

Video, projection, and LED content management (`libs/uzume/prism/src`) — ~11K
LOC across 15 engines. Vendor integrations include
`brompton-tessera-led-processor-management-engine`,
`disguise-media-server-integration-engine`,
`generic-media-server-control-protocol-adapter-engine`,
`notch-vfx-integration-engine`, `resolume-arena-integration-engine`, and
`touchdesigner-integration-engine`. Core video features cover
`projection-mapping-engine`, `projection-auto-alignment-engine`,
`led-wall-layout-designer-engine`, `video-routing-matrix-engine`,
`video-content-management-engine`, `content-preflight-checker-engine`,
`video-color-pipeline-management-engine`, `imag-camera-management-engine`, and
`video-signal-redundancy-engine`.

### @uzume/pyra

Special effects, pyrotechnics, and atmospheric systems (`libs/uzume/pyra/src`) —
~11.8K LOC across 18 engines. Pyro and laser
(`pyrotechnic-cue-management-engine`,
`pyrotechnic-firing-system-integration-engine`, `flame-effect-control-engine`,
`nfpa-1126-compliance-documentation-generator`,
`pyrotechnic-inventory-chain-of-custody-engine`, `ilda-laser-control-engine`),
atmospherics (`co2-cryogenic-jet-control-engine`,
`fog-haze-machine-management-engine`, `low-fog-system-control-engine`,
`multi-effect-machine-control-engine`), scent (`scent-machine-control-engine`,
`scent-palette-library-management-engine`, `scent-zone-management-engine`,
`scent-consumables-safety-management-engine`), and water
(`water-screen-projection-system-control-engine`,
`fountain-choreography-engine`,
`water-effect-safety-environmental-management-engine`), tied together by
`multi-sensory-effect-choreography-engine`.

### @uzume/scena

Scenic design, construction planning, and props workflows
(`libs/uzume/scena/src`) — ~8.2K LOC across 10 engines:
`scenic-design-workspace-engine`, `cad-file-import-engine`,
`scenic-construction-documentation-generator-engine`,
`scenic-materials-library-engine`, `scenic-revision-tracking-engine`,
`scenic-props-management-engine`, `scenic-props-preset-tracking-engine`,
`scenic-paint-reference-system-engine`, `scenic-truck-pack-planning-engine`, and
`scenic-budget-tracker-engine`. It is the set-and-props department from design
through build, packing, and budget.

### @uzume/sonos

Audio engineering, routing, and spatial sound control (`libs/uzume/sonos/src`) —
~12.6K LOC across 25 engines, the audio counterpart to `@uzume/lumina`. It
covers AV-over-IP (`dante-network-management-engine`,
`aes67-interoperability-engine`, `audio-patch-management-engine`), system design
(`line-array-design-engine`, `delay-system-calculator-engine`,
`subwoofer-array-configuration-engine`, `gain-structure-calculator-engine`,
`acoustic-modeling-engine`, `immersive-audio-object-engine`), RF and IEM
(`rf-frequency-coordination-engine`,
`wireless-microphone-monitoring-dashboard-engine`, `iem-mix-management-engine`,
`rf-spectrum-visualization-engine`, `rf-venue-coordination-database-engine`),
playback (`ableton-live-integration-engine`, `qlab-integration-engine`,
`stem-playback-management-engine`,
`click-track-guide-track-distribution-engine`,
`redundant-playback-system-monitoring-engine`), and the orchestra pit
(`conductor-camera-management-system-engine`,
`musician-personal-monitor-management-engine`,
`pit-configuration-management-engine`, `music-stand-display-system-engine`,
`pit-communication-system-engine`).

### @uzume/tesla

Power distribution, electrical planning, and monitoring (`libs/uzume/tesla/src`)
— ~7.4K LOC across 10 engines: `single-line-diagram-designer-engine`,
`circuit-loading-calculator-engine`, `generator-sizing-calculator-engine`,
`circuit-mapping-documentation-engine`, `dimmer-rack-management-engine`,
`power-monitoring-dashboard-engine`, `power-quality-monitoring-alerting-engine`,
`ups-backup-power-management-engine`, `electrical-safety-management-engine`, and
`cable-connector-management-engine`. It is the electrical-engineering department
— sizing, documenting, and monitoring the power that every other subsystem
draws.

### @uzume/vestis

Costume, wardrobe, and quick-change management (`libs/uzume/vestis/src`) — ~8K
LOC across 10 engines: `costume-plot-management-engine`,
`fitting-schedule-management-engine`, `garment-maintenance-scheduling-engine`,
`led-costume-control-engine`, `makeup-design-reference-system-engine`,
`quick-change-choreography-documentation-engine`,
`wardrobe-inventory-rfid-tracking-engine`, `wardrobe-budget-tracking-engine`,
`wearable-technology-testing-maintenance-system-engine`, and
`wig-and-hairpiece-management-system-engine`. It is the wardrobe department,
including the wearable-tech/LED-costume bridge into the show-control layer.