Ooloi is a complete music-notation platform built in Clojure. It demonstrates how functional architecture, when applied rigorously, can yield not only mathematical clarity but also production-level performance and reliability. Every subsystem—data model, concurrency, traversal, serialization—exists to express musical structure without compromise.
Core Architectural Principles
1. Polymorphic Design
Ooloi’s model layer is entirely polymorphic. All musical objects—notes, articulations, dynamics, staves, measures—implement shared traits via Clojure multimethods, extended by the Methodical library.
Polymorphism here isn’t stylistic abstraction: it’s structural. Each musical element can declare behaviour (attach, transpose, render, serialize) without entangling hierarchies. The result is an open semantic ontology rather than a closed class tree.
2. Immutable Data Model
All musical data lives in immutable defrecords. Every operation returns a new instance; nothing is mutated in place. Persistence enables complete transactional safety and reproducible state across threads, sessions, or machines.
This immutability is not ideological—it underpins distributed collaboration, deterministic rendering, and repeatable MusicXML export.
3. STM-Concurrent Transaction Layer
Every modification occurs inside Clojure’s Software Transactional Memory (STM). Refs, dosync blocks, and automatic retries provide ACID-compliant concurrency without locks. The backend can sustain many hundreds of thousands updates per second with zero data races. Every client operation—whether local or gRPC remote—commits through the same STM substrate, guaranteeing consistency across network boundaries.
4. Functional Traversal: Timewalking
Traversal of musical structures uses pure push-based transducers, not lazy sequences. The timewalk system processes [item vpd position] tuples in temporal order, emitting directly into a reducing function with zero intermediate allocation. It supports true early termination and composable pipelines for harmonic analysis, playback, and rendering. Benchmarks confirm throughput of ~1M pitches/second for full orchestral scores—constant memory, constant time per item.
5. Selective Hash-Consing and Memory Canonicalization
Global caches deduplicate identical musical objects across the system. A 50 000-note score serializes to 14.5 KB (≈ 0.29 bytes/note), roughly 1 000× smaller than equivalent MusicXML. Hash-consing operates transparently at constructor level; a background daemon restores shared identity during idle cycles.
6. Specter-Driven Structural Updates
Clojure’s Specter library provides high-performance, path-aware updates of nested data. Combined with compact VPD addressing ([:m 0 1 2 3] form), it enables efficient mutation of deep score hierarchies without object churn. Specter paths resolve via cached accessors; all operations remain pure functions over persistent data.
7. Testing as Architecture
Ooloi’s tests (19000+ and growing) form part of the architecture itself. Tests are written with Midje, using property-based generators for musical data and integration tests for real gRPC components. Coverage exceeds 95%, but more importantly, every test is deterministic: identical seeds yield identical musical objects, making regression analysis and performance benchmarking reproducible.
8. API Layer and gRPC Integration
The system exposes a unified API via gRPC. Each API call is a transactional operation in the STM layer, surfaced through generated Clojure macros (`SRV/*`) that hide all networking details. Developers can call:
Core Architectural Principles
1. Polymorphic Design
Ooloi’s model layer is entirely polymorphic. All musical objects—notes, articulations, dynamics, staves, measures—implement shared traits via Clojure multimethods, extended by the Methodical library.
Polymorphism here isn’t stylistic abstraction: it’s structural. Each musical element can declare behaviour (attach, transpose, render, serialize) without entangling hierarchies. The result is an open semantic ontology rather than a closed class tree.
2. Immutable Data Model
All musical data lives in immutable defrecords. Every operation returns a new instance; nothing is mutated in place. Persistence enables complete transactional safety and reproducible state across threads, sessions, or machines.
This immutability is not ideological—it underpins distributed collaboration, deterministic rendering, and repeatable MusicXML export.
3. STM-Concurrent Transaction Layer
Every modification occurs inside Clojure’s Software Transactional Memory (STM). Refs, dosync blocks, and automatic retries provide ACID-compliant concurrency without locks. The backend can sustain many hundreds of thousands updates per second with zero data races. Every client operation—whether local or gRPC remote—commits through the same STM substrate, guaranteeing consistency across network boundaries.
4. Functional Traversal: Timewalking
Traversal of musical structures uses pure push-based transducers, not lazy sequences. The timewalk system processes [item vpd position] tuples in temporal order, emitting directly into a reducing function with zero intermediate allocation. It supports true early termination and composable pipelines for harmonic analysis, playback, and rendering. Benchmarks confirm throughput of ~1M pitches/second for full orchestral scores—constant memory, constant time per item.
5. Selective Hash-Consing and Memory Canonicalization
Global caches deduplicate identical musical objects across the system. A 50 000-note score serializes to 14.5 KB (≈ 0.29 bytes/note), roughly 1 000× smaller than equivalent MusicXML. Hash-consing operates transparently at constructor level; a background daemon restores shared identity during idle cycles.
6. Specter-Driven Structural Updates
Clojure’s Specter library provides high-performance, path-aware updates of nested data. Combined with compact VPD addressing ([:m 0 1 2 3] form), it enables efficient mutation of deep score hierarchies without object churn. Specter paths resolve via cached accessors; all operations remain pure functions over persistent data.
7. Testing as Architecture
Ooloi’s tests (19000+ and growing) form part of the architecture itself. Tests are written with Midje, using property-based generators for musical data and integration tests for real gRPC components. Coverage exceeds 95%, but more importantly, every test is deterministic: identical seeds yield identical musical objects, making regression analysis and performance benchmarking reproducible.
8. API Layer and gRPC Integration
The system exposes a unified API via gRPC. Each API call is a transactional operation in the STM layer, surfaced through generated Clojure macros (`SRV/*`) that hide all networking details. Developers can call:
instead of manually building protocol buffers. Transport (in-process vs. network) is transparent; both paths execute identical code.
9. Plugin Architecture (JVM-Wide)
Plugins are first-class citizens implemented in any JVM language—Clojure, Kotlin, Scala, Java, etc. Plugin defrecords maintain perfect round-trip fidelity across gRPC boundaries (`(= original (roundtrip original))` always true). Dynamic constructor caching allows hot installation and unloading without restart. All plugin types—importers, renderers, analyzers—participate natively in the trait and API systems.
10. Performance and Determinism
All systems are designed for deterministic parallelism: identical operations produce identical bytes, independent of thread count or execution order.
This property is crucial for MusicXML round-tripping and collaborative editing, ensuring that semantic equality implies binary equality.
Ooloi is an executable argument for functional architecture: immutable data, STM concurrency, and composable transducers yield not theoretical elegance but measurable, falsifiable performance and reliability.
For detailed specifications, benchmarks, and design rationale, see the Architecture Decision Records (ADRs) and the Guides in the documentation section.
9. Plugin Architecture (JVM-Wide)
Plugins are first-class citizens implemented in any JVM language—Clojure, Kotlin, Scala, Java, etc. Plugin defrecords maintain perfect round-trip fidelity across gRPC boundaries (`(= original (roundtrip original))` always true). Dynamic constructor caching allows hot installation and unloading without restart. All plugin types—importers, renderers, analyzers—participate natively in the trait and API systems.
10. Performance and Determinism
All systems are designed for deterministic parallelism: identical operations produce identical bytes, independent of thread count or execution order.
This property is crucial for MusicXML round-tripping and collaborative editing, ensuring that semantic equality implies binary equality.
Ooloi is an executable argument for functional architecture: immutable data, STM concurrency, and composable transducers yield not theoretical elegance but measurable, falsifiable performance and reliability.
For detailed specifications, benchmarks, and design rationale, see the Architecture Decision Records (ADRs) and the Guides in the documentation section.