Uzume Domain — Architecture

Named after Ame-no-Uzume-no-Mikoto — the Shinto goddess who performed the first show in recorded mythology — Uzume is the Oshun platform for everything that happens between "the doors open" and "the last cable is struck."

Overview#

Uzume is a library-only domain — it exposes no standalone applications or services. Its 22 libraries (21 TypeScript + 1 Rust/WASM workspace) are consumed by higher-level applications that build production management, show control, and live event tooling on top of the Uzume API surface.

The domain solves a fundamental fragmentation problem in live entertainment: productions currently rely on 7–10 incompatible specialist tools (lighting console software, audio system tools, video servers, automation controllers, stage management software, production management platforms, safety tools) with no integration layer. Uzume provides that layer — a single, typed API surface spanning lighting, audio, video, rigging, special effects, staging, costume, scheduling, safety, AI, and broadcast.

Because Uzume ships no services of its own, the boundary between Uzume and the rest of the Oshun platform is very clean: Uzume libraries are pure computation and protocol libraries that consuming applications wire up with their own HTTP APIs, authentication middleware, and user interfaces.

Domain Architecture#

The diagram below shows how the layers relate. At the bottom sits the Rust protocol engine, which handles timing-critical operations that TypeScript cannot execute with sufficient precision. Above that is @uzume/core, the common foundation all subsystem libraries depend on. The subsystem libraries sit in parallel — they are deliberately isolated from one another. The AI and show control layers sit above the subsystems and coordinate them. Consuming applications sit at the top.

+──────────────────────────────────────────────────────────────────────────+
│                        APPLICATION LAYER                                  │
│           (Applications built on top of Uzume libraries)                 │
│                                                                          │
│   Production Management App    Show Control App    Technical Design App  │
+──────────────────────────────────────────────────────────────────────────+
                                    |
+──────────────────────────────────────────────────────────────────────────+
│                          AI INTELLIGENCE                                  │
│                          @uzume/muse                                     │
│    (AI cue placement, NLP show control, generative content, anomaly)     │
+──────────────────────────────────────────────────────────────────────────+
                                    |
+─────────────────────────────────────────────────────────────────────────────+
│                        SUBSYSTEM LIBRARIES                                   │
│                                                                             │
│  BROADCAST    VIDEO     AUDIO    STAGE    SCENIC   RIGGING   SAFETY        │
│  @broadcast  @prism   @sonos   @koru    @scena   @kinesis  @aegis          │
│  @aurora     @previz  @echo                       @lumina   @tesla         │
│                                                   @pyra     @forge         │
│                                                   @vestis   @hermes        │
│                                                             @atlas         │
│                                                             @chronos       │
+─────────────────────────────────────────────────────────────────────────────+
                                    |
+──────────────────────────────────────────────────────────────────────────+
│                        SHOW CONTROL BRIDGE                                │
│                        @uzume/nexus                                      │
│    (Protocol bridging, subsystem integration, unified control layer)     │
+──────────────────────────────────────────────────────────────────────────+
                                    |
+──────────────────────────────────────────────────────────────────────────+
│                     PROTOCOL INFRASTRUCTURE                               │
│                                                                          │
│     uzume-protocol-engines (Rust/WASM)                                  │
│     (SMPTE timecode, network I/O, WASM control surface, Node.js bridge) │
+──────────────────────────────────────────────────────────────────────────+
                                    |
+──────────────────────────────────────────────────────────────────────────+
│                         CORE FRAMEWORK                                    │
│                          @uzume/core                                     │
│    (Config, database, errors, event bus/NATS, logging, utilities)        │
+──────────────────────────────────────────────────────────────────────────+

Library Organization#

Core Infrastructure#

@uzume/core — Foundation Framework#

Every other Uzume library depends on @uzume/core. It is the single source of truth for shared types, database schema, configuration, event bus, logging, and protocol math utilities. The package is organized into seven modules:

The package root export (src/index.ts) re-exports config, database, errors, event-bus, logging, and utils. The types/ module is exposed through the dedicated @uzume/core/types subpath export, so consumers can import domain types without pulling in the runtime infrastructure modules.

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

@uzume/nexus — Show Control Protocol Bridge#

The Nexus is intended to be the integration backbone for connecting the disparate protocols of live production into a unified control layer — bridging DMX/sACN/Art-Net from lighting, OSC from audio and video systems, and other protocols through a common event-driven API.

The current @uzume/nexus TypeScript package is a metadata-only library: src/index.ts exports UZUME_NEXUS_METADATA and getUzumeNexusMetadata(). The actual protocol-bridging engines (Art-Net, sACN, OSC, MIDI/MSC, timecode, the master timeline, and cross-subsystem cue sequencing) are implemented in the Rust uzume-protocol-engines workspace and consumed through the napi-rs native module and the WASM control surface.

uzume-protocol-engines — Rust/WASM Protocol Workspace#

A polyglot Rust crate workspace for performance-critical protocol code that TypeScript cannot execute with sufficient precision or throughput. The workspace contains six crates:

The WASM build enables browser-based control surfaces (lighting consoles, stage manager panels) that require direct protocol access without a server round-trip. The Node.js bridge enables the server-side TypeScript tier to call Rust code for timing-critical operations without leaving the Node.js process.

Subsystem Libraries#

Each subsystem library is independent. Subsystems do not import from other subsystem libraries — all inter-subsystem coordination happens through the NATS event bus provided by @uzume/core. This isolation ensures that a lighting library update never breaks the rigging library and that a show control network can load only the subsystems relevant to a given production.

Broadcast and Streaming Group#

Audio Group#

Stage and Scenic Group#

Technical Systems Group#

Operations Group#

AI Group#

Design Patterns#

The following patterns apply consistently across the domain. Understanding them is essential before reading the individual library specifications.

1. Event-Driven Subsystem Coordination#

No subsystem library imports another subsystem library. Coordination is achieved entirely through the NATS event bus. For example, when the audio engineer marks a cue ready, @uzume/sonos publishes uzume.cue.department.ready on the bus. @uzume/koru (stage management) subscribes and updates the cue status display.

This pattern means:

• Subsystems can be updated independently without breaking others
• Show control networks can selectively subscribe — a system without video production does not load video-related listeners
• New subsystems can integrate by subscribing to existing events without any change to existing libraries

2. Polyglot Rust/WASM for Protocol Precision#

Show control requires precision that TypeScript's event loop cannot guarantee. A SMPTE timecode engine that fires one frame late (33ms at 30fps) will cause visible mis-syncs between lighting, video, and effects. The Rust uzume-timing-core crate delivers sub-microsecond precision.

The polyglot boundary is explicit and deliberate:

• TypeScript calls Rust via the Node.js native module (napi-rs) for server-side operations
• Browser control surfaces load the WASM build directly, eliminating the server round-trip for real-time control

3. Centralized Configuration Schema#

@uzume/core/config defines a single Zod environment schema (UzumeConfigSchema) covering database, Redis, NATS, object storage, and 13 subsystem feature flags. Configuration is validated and cached at startup (loadUzumeConfig), so misconfiguration fails fast rather than mid-show, and any tooling that consumes the core library can read the same typed config.

4. Database Schema in Core Only#

Only @uzume/core defines a database schema and Drizzle ORM integration — a single PostgreSQL uzume schema with 24 tables and 19 enums. Keeping the schema in one place avoids 22 separate schemas and schema-conflict issues. Subsystem libraries are pure computation libraries; persistence is the responsibility of @uzume/core and the consuming application layer.

5. WASM Control Surfaces#

The uzume-control-surface-wasm crate enables browser-based control panels with direct protocol access. A lighting operator can run a full DMX-aware control surface in a browser tab — pointing at a performance network's protocol engines — without any custom application install. This is particularly valuable in:

• Spare operator panel scenarios (tablet-based backup control)
• Remote monitoring and supervisory control
• Educational and training environments

Dependency Model#

The dependency graph has three tiers. The Rust workspace has no TypeScript dependencies; the TypeScript core builds on shared Oshun libraries; all subsystems peer-depend on core. Nothing flows sideways between subsystems.

uzume-protocol-engines (Rust — no TypeScript dependencies)
    |
    |  (native module / WASM)
    v
@uzume/core (TypeScript — depends on @oshun/* shared libraries)
    |
    +─── @uzume/nexus
    |
    +─── 19 subsystem libraries (@uzume/broadcast, @uzume/prism, @uzume/muse, etc.)

The 20 non-core TypeScript subsystem libraries (@uzume/nexus and the 19 subsystems) list @uzume/core as a peerDependency (workspace:*). @uzume/core itself depends on the shared @oshun/* packages plus nats, drizzle-orm, and zod. The Rust workspace has no TypeScript dependencies — it compiles independently and exposes its API surface through the native bridge and WASM module boundaries.

Service Topology#

Uzume is a library-only domain with no standalone services. It does, however, require external infrastructure that consuming applications must provision. A consuming application is responsible for bringing up these services and providing their connection URLs via the environment variables defined in @uzume/core/config.

There is no HTTP server in the Uzume domain. REST APIs, if needed, are implemented by the consuming application layer.

Technology Stack#

Build and Development#

The Nx commands below work for day-to-day TypeScript library development. When Nx is broken by worktree conflicts, bypass it with npx vitest run and npx tsc --noEmit directly from the library directory.

# TypeScript library tests
pnpm nx test @uzume/core
pnpm nx test @uzume/broadcast

# Build a TypeScript library
pnpm nx build @uzume/core

# Run all Uzume TypeScript tests
pnpm nx run-many --target=test --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

# Type check without Nx (worktree conflict avoidance)
cd libs/uzume/core && npx tsc --noEmit

Domain Boundaries#

Understanding what Uzume owns and what it deliberately delegates to the consuming application layer prevents duplication and misplaced dependencies. All of the following "Uzume does not provide" items exist elsewhere in the Oshun platform — they are omissions by design, not gaps. This architecture was verified against libs/uzume/* as part of TODO Phase 62.

Uzume provides:

• All live production technical infrastructure (lighting, audio, video, rigging, effects)
• All production operations tools (stage management, crew, scheduling, budgets, safety)
• Protocol implementations for AV hardware integration
• WASM control surfaces for browser-based production panels

Uzume does not provide:

• HTTP APIs — consuming applications provide their own REST/GraphQL layer; Uzume libraries contain no server code
• Authentication or user management — delegated to consuming applications via @oshun/auth; Uzume libraries assume the calling layer has already established identity
• AI model hosting — AI features in @uzume/muse call external model providers; Uzume is a client, not a host
• Physical hardware — Uzume controls hardware through network protocols (Art-Net, sACN, OSC, MIDI), not direct I/O; the physical interface layer sits in the venue hardware itself