Euterpe Domain — Architecture

Tags: scope:euterpe · layer:domain · type:lib

Overview#

Euterpe is the comprehensive music technology domain for the Oshun ecosystem. Named after the Greek Muse of music and lyric poetry, Euterpe answers a fundamental question every creative platform faces: where does the music intelligence live? Rather than scattering pitch math, audio analysis, AI generation, mastering logic, and voice synthesis across dozens of application teams, Euterpe centralises all of it in a single, well-layered library tier. Any application in the ecosystem — Calliope's AI artist platform, Yemaya's creative studio, Isis's generative factory — can import the same primitives rather than reinventing them.

Euterpe is a library-only domain — it exposes no standalone services. Most functionality is provided as TypeScript (ESM) packages consumed by higher-level applications and other domains, alongside a Rust DSP and realtime-audio subsystem — the audio-engine (with the dsp-core, dsp-graph, and dsp-wasm crates), realtime-engine (mrt2-core, mrt2-engine, mrt2-native), and instrument crates, 62 .rs files across 9 Cargo.toml manifests — for the latency-critical signal processing that ESM cannot serve. The domain is organized into distinct functional layers, with a strict bottom-up dependency graph ensuring that primitive abstractions never depend on higher-level concerns.

The domain ships ~47 TypeScript packages under libs/euterpe/: the original 34 from TODO Phase 38 sections 38.1–38.34, @euterpe/ai-scoring (Phase 70.6), and the 10 packages that earlier revisions listed as planned — @euterpe/providers, elevenlabs, lyria, projects, workflows, api, provenance, evals, ops, studio-runtime (Phase 38.35–38.44) — which are now implemented with real TypeScript source. The only still-pending Phase-38 deliverable is the browser DAW application (apps/euterpe/studio-web, Phase 38.45), which is so far a placeholder directory (a .gitignore only). See specifications.md §1 for the full inventory.

Layer Architecture#

The seven foundational libraries are arranged in four conceptual layers. Each layer builds on the one below it: higher layers may use lower-layer primitives, but lower layers never import higher-layer code. This keeps the foundational libraries lean, universally reusable, and free of circular dependencies.

+────────────────────────────────────────────────────────────────────────+
│                         PRODUCTION LAYER                               │
│                                                                        │
│    @euterpe/studio        @euterpe/master      @euterpe/voice          │
│    (DAW engine,           (mastering chain,    (cloning,               │
│     timeline, mixer,       mix analysis,        conversion,            │
│     effects, instruments,  stem mastering,      TTS, singing,          │
│     automation, AI)        format masters,      choir,                 │
│                            AI mix assistant)    analysis)              │
│                                                                        │
│    @euterpe/spatial                                                     │
│    (Dolby Atmos, binaural,                                             │
│     ambisonics, VR audio,                                              │
│     AI spatial upmix)                                                  │
+────────────────────────────────────────────────────────────────────────+
                                    |
+────────────────────────────────────────────────────────────────────────+
│                         GENERATION LAYER                               │
│                                                                        │
│    @euterpe/genesis                                                     │
│    (text-to-music, stem separation, voice generation,                  │
│     melody generation, arrangement, inpainting,                        │
│     style transfer, conditional generation,                            │
│     quality assessment, model infrastructure)                          │
+────────────────────────────────────────────────────────────────────────+
                                    |
+────────────────────────────────────────────────────────────────────────+
│                          THEORY LAYER                                  │
│                                                                        │
│    @euterpe/theory                                                      │
│    (harmony, counterpoint, melody, progressions,                       │
│     groove, set theory, orchestration, genre,                          │
│     ear training, notation)                                            │
+────────────────────────────────────────────────────────────────────────+
                                    |
+────────────────────────────────────────────────────────────────────────+
│                           CORE LAYER                                   │
│                                                                        │
│    @euterpe/core  (zero dependencies)                                  │
│    (notes, intervals, scales, chords, rhythm,                          │
│     keys, form, dynamics, audio, MIDI)                                 │
+────────────────────────────────────────────────────────────────────────+

Beyond these seven foundational libraries, the domain ships an additional 28 implemented libraries at the production and application tier — virtuoso, stage, conservatory, score, collab, discover, chain, synth, lyrics, iot, agents, distribution, sacred, history, philosophy, acoustics, protect, video, samples, restore, marketing, analytics, transcribe, accompany, guitar, access, podcast, and ai-scoring — all catalogued in features.md and specifications.md.

Library Organization#

Layer 1: Core (@euterpe/core)#

The foundation layer with zero runtime dependencies. Every other Euterpe library depends on it (directly or transitively). @euterpe/core is suitable for use in any JavaScript environment — browser, Node.js, edge runtime, or WASM host — because it carries no external dependencies. It contains ten sub-modules:

Layer 2: Theory (@euterpe/theory)#

Builds on core to add music intelligence — analysis, rule-checking, and generation grounded in centuries of compositional practice. Ten sub-modules:

Layer 3: Generation (@euterpe/genesis)#

AI-powered music creation. Depends on both core and theory, using theory primitives (scales, progressions, orchestration ranges) to constrain and evaluate the output of neural generative models. Ten sub-modules:

Layer 4: Production Libraries#

Four libraries form the production tier, each targeting a distinct professional discipline. @euterpe/studio, @euterpe/master, and @euterpe/voice build conceptually on core and theory; @euterpe/studio also builds on genesis for its AI-assisted production features. @euterpe/spatial builds on core alone, because spatial audio processing is a signal-processing discipline that operates on audio buffers independently of music theory. As noted in Design Pattern 1, this layering is conventional — none of these relationships is a declared package.json dependency.

@euterpe/studio (DAW Engine)#

A full Digital Audio Workstation engine in library form. Ten sub-modules: daw-engine, timeline, clip-editing, midi-editing, mixer, effects, instruments, automation, project-management, ai-features. Yemaya embeds this library as its DAW engine.

@euterpe/master (Mastering)#

Professional audio mastering — the final stage of music production before distribution. Five sub-modules: mastering-chain, mix-analysis, stem-mastering, format-masters, mix-assistant. Also owns the loudness math for V2 commentary mix ducking (see Cross-Domain Integration Points).

@euterpe/spatial (Spatial Audio)#

Immersive audio processing for cinema, VR, and broadcast. Five sub-modules: atmos, binaural, ambisonics, vr-audio, spatial-upmix.

@euterpe/voice (Voice Technology)#

Voice synthesis and processing across seven sub-modules: voice-cloning, voice-conversion, tts, text-to-singing, vocal-processing, choir, voice-analysis. All voice-cloning and conversion operations are consent-gated at the type level (see Design Pattern 5).

Dependency Topology#

The topology below shows the conceptual layering among the seven foundational libraries. Arrows run from a library toward its dependencies; a higher library uses primitives from a lower one. These are not declared package.json dependencies — see Design Pattern 1.

@euterpe/core
    │
    ├─── @euterpe/theory ──────────────────────────────────────────┐
    │         │                                                     │
    │         ├─── @euterpe/genesis ────────────────────────────┐  │
    │         │         │                                       │  │
    │         │         └─── @euterpe/studio ◄──────────────────┘  │
    │         │                                                     │
    │         ├─── @euterpe/master ◄─────────────────────────────  │
    │         │                                                     │
    │         └─── @euterpe/voice ◄──────────────────────────────  │
    │                                                               │
    └─── @euterpe/spatial (core layer only) ◄──────────────────────┘

@euterpe/spatial is intentionally isolated from the theory layer. Spatial audio processing is fundamentally a signal-processing discipline that operates on audio buffers — knowing that a chord is a ii7 chord adds nothing to an HRTF convolution. Keeping the theory layer out of spatial means the spatial library stays conceptually lightweight and universally applicable, even in contexts (such as game audio or film post-production) where no music theory is present.

The remaining 28 implemented libraries (virtuoso, stage, conservatory, score, collab, discover, chain, synth, lyrics, iot, agents, distribution, sacred, history, philosophy, acoustics, protect, video, samples, restore, marketing, analytics, transcribe, accompany, guitar, access, podcast, ai-scoring) sit at the production and application tier and build conceptually on the lower layers.

Design Patterns#

1. Layered Dependency Direction#

The domain enforces a strict bottom-up layering: a lower layer never imports a higher one. In practice, the libraries do not declare each other in package.json — every Euterpe package.json carries an empty dependencies map and vitest as the only dev dependency. Inter-package use, where it occurs, resolves through the monorepo's TypeScript path mappings, and the layering is maintained by convention and by the dependency direction shown in the topology diagram above.

2. Sub-module Organization#

Each library is internally organized into per-feature sub-modules under src/ (e.g. core/src/scales, theory/src/harmony), each with its own types.ts, implementation file, and spec file. The sub-modules are re-exported through a single barrel — every package.json declares one export, ".", mapping to src/index.ts. Consumers import from the package root, not from per-sub-module paths, which keeps the internal structure freely refactorable.

3. Pure Functional Core#

The core and theory layers are implemented as pure functions and immutable data structures wherever possible. This design supports testability (no side effects to mock), composability (outputs can be fed into subsequent operations without copying), and concurrent use without shared mutable state.

4. Infrastructure Abstraction in Genesis#

The infrastructure sub-module in @euterpe/genesis abstracts model loading, GPU/CPU dispatch, and batching behind a stable interface. Model backends can therefore be swapped (diffusion → transformer, local → cloud) without changing the API surface of generation functions. The planned @euterpe/providers package will own actual provider connectivity on top of this abstraction.

5. Consent-Gated Voice Operations#

Voice cloning and conversion operations require a ConsentRecord on the source VoiceModel. This is enforced at the type level — operations that modify voice identity will not compile without a consent record, making consent a structural requirement rather than a runtime check. @euterpe/protect voice deepfake detection also cross-references ConsentRecord to determine whether a detected synthetic voice is authorized.

Technology Stack#

The following table summarises the technologies used across the Euterpe libraries.

Build and Development#

The commands below assume a working Nx monorepo setup. Because Euterpe has no services to start, development is entirely build-and-test.

# Test a specific library
pnpm nx test @euterpe/core

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

# Lint a specific library
pnpm nx lint @euterpe/theory

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

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

Service Topology#

Euterpe has no services. There is no database, no HTTP server, no event bus, and no background workers. The domain is a pure library tier.

Applications that embed Euterpe libraries (such as Calliope, Isis, or Yemaya) are responsible for their own service infrastructure. Euterpe provides the music intelligence; the host application provides the runtime context, persistence, and network exposure.

Domain Boundaries#

Understanding what Euterpe does and does not own is essential for engineers routing new features to the right domain.

Euterpe provides:

• All music theory logic, analysis, and generation
• All audio DSP, format handling, and MIDI protocol
• All spatial audio processing
• All voice synthesis and processing

Euterpe does not provide:

• Storage or persistence — the host application owns this; Euterpe data structures live in memory only
• Authentication or authorization
• HTTP APIs — no REST or GraphQL server; the planned @euterpe/api package provides typed contracts that a host application mounts on its own HTTP runtime
• Event bus integration — no NATS or message queue
• Copyright adjudication — analysis and similarity scoring belong to @euterpe/protect; legal determination is delegated to the Themis domain (Music Shield and Universal Originality Shield)

Cross-Domain Integration Points#

Euterpe functions as a shared music intelligence layer for several other domains. The table below lists each consuming domain, what it consumes, and why the boundary is drawn where it is.

Two V2 game-stack bridge services also consume Euterpe libraries directly:

• apps/v2/euterpe-commentary-ducking — consumes @euterpe/master mastering primitives (loudness delta, dB/linear conversion, sidechain envelope math) to lower the V2.DynamicMusic bus under the V2.Commentary bus. The mastering boundary exists because the loudness math is domain knowledge that belongs in the mastering library, not scattered across bridge code.
• apps/v2/karaoke-rhythm-combat-bridge — consumes @euterpe/genesis, @euterpe/accompany, and @euterpe/protect for procedural backing tracks, adaptive accompaniment, and streamer-safe music swap. V2 owns final scoring thresholds and rollback state; Euterpe owns the music production.