# 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: | Module | Purpose | | ------------ | --------------------------------------------------------------------- | | `config/` | Zod environment configuration schema and feature flags | | `database/` | Drizzle ORM schema, migrations, and seed generator | | `errors/` | Domain-specific error hierarchy, routing, and safety escalation | | `event-bus/` | NATS-based event publication and subscription | | `logging/` | Structured subsystem logging with correlation propagation | | `types/` | Domain objects, protocol types, and Zod schemas (`@uzume/core/types`) | | `utils/` | SMPTE timecode, DMX, protocol-address, safety, and unit math | 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: | Crate | Role | | ---------------------------- | --------------------------------------------------- | | `uzume-protocol-types` | Shared protocol type definitions used across crates | | `uzume-timing-core` | Sub-microsecond SMPTE timecode engine | | `uzume-network-io` | High-throughput network I/O for AV protocol streams | | `uzume-node-bridge` | napi-rs bindings for Node.js native module | | `uzume-control-surface-wasm` | wasm-bindgen browser control surface | | `uzume-integration-tests` | Cross-crate integration test suite | 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 | Library | Engines | Focus | | ------------------ | ------- | ------------------------------------------------------------- | | `@uzume/broadcast` | 10 | Broadcast switching, streaming, replay, recording, simulcast | | `@uzume/prism` | 15 | Media servers, LED walls, projection mapping, video routing | | `@uzume/aurora` | 25 | XR stages, drone shows, digital twins, RTLS, motion capture | | `@uzume/previz` | 15 | 3D rendering, VR walkthroughs, collaborative previsualization | #### Audio Group | Library | Engines | Focus | | -------------- | ------- | -------------------------------------------------------------- | | `@uzume/sonos` | 25 | Mixing consoles, speaker systems, spatial audio, RF management | | `@uzume/echo` | 20 | Accessibility, audience interaction, wearables, analytics | #### Stage and Scenic Group | Library | Engines | Focus | | --------------- | ------- | -------------------------------------------------------- | | `@uzume/koru` | 15 | Cue calling, rehearsal management, blocking, run-of-show | | `@uzume/scena` | 10 | Scenic design, construction docs, props, truck pack | | `@uzume/vestis` | 10 | Costume plots, fittings, quick-change, RFID tracking | #### Technical Systems Group | Library | Engines | Focus | | ---------------- | ------- | ------------------------------------------------------------- | | `@uzume/lumina` | 20 | Fixtures, DMX/sACN/Art-Net, cue programming, pixel mapping | | `@uzume/kinesis` | 30 | Hoists, flying systems, automation, robotics, animatronics | | `@uzume/pyra` | 18 | Pyrotechnics, lasers, fog, CO2, flame, confetti, scent, water | | `@uzume/tesla` | 10 | Power diagrams, load calc, generators, real-time monitoring | #### Operations Group | Library | Engines | Focus | | ---------------- | ------- | -------------------------------------------------------------- | | `@uzume/forge` | 10 | Network topology, VLANs, PTP, bandwidth, Wi-Fi, security | | `@uzume/hermes` | 10 | Intercom, messaging, video monitoring, translation | | `@uzume/atlas` | 24 | Budgets, crew, equipment, touring, sustainability, vendor mgmt | | `@uzume/chronos` | 10 | Timelines, rehearsal schedules, calendars, resource leveling | | `@uzume/aegis` | 30 | Risk, inspections, weather, crowd safety, OSHA/NFPA compliance | #### AI Group | Library | Engines | Focus | | ------------- | ------- | ------------------------------------------------------ | | `@uzume/muse` | 15 | AI cue placement, generative content, NLP show control | --- ## 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`. | Infrastructure | Purpose | Required By | | ---------------- | -------------------------------- | -------------------------------- | | PostgreSQL | Production data persistence | `@uzume/core` | | NATS | Real-time event bus | `@uzume/core` and all subsystems | | Redis (optional) | Caching for high-frequency state | Consuming applications | There is no HTTP server in the Uzume domain. REST APIs, if needed, are implemented by the consuming application layer. --- ## Technology Stack | Component | Technology | | ----------------- | ---------------------------------------- | | Primary language | TypeScript (ESM, strict mode) | | Protocol language | Rust (Rust edition 2021) | | TypeScript build | `@nx/js:tsc` | | Rust build | Cargo workspace + wasm-pack | | Testing | Vitest (TypeScript), `cargo test` (Rust) | | Database ORM | Drizzle ORM | | Event bus | NATS (via `nats` npm package) | | Schema validation | Zod | | Node.js native | napi-rs | | Browser WASM | wasm-bindgen | --- ## 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. ```bash # 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