​People occasionally ask how one person builds something this size. The honest answer involves an AI, and since honesty is the whole method here, it's worth describing how that actually works. The reality is less glamorous and more interesting than either the sceptics or the enthusiasts imagine.

Ooloi is developed with Claude Code as the primary implementor. It writes a great deal of the code and most of the tests. What it doesn't do is decide anything. Every architectural decision lives in an ADR before implementation begins; the ADRs function as binding specifications, and the AI works inside them. Development proceeds test-first, consultationally: we discuss what a subsystem must do, the semantics get pinned down, the tests get written, and only then does implementation start. No code is committed unless something was broken, then fixed, and the full suite has returned to green.

None of this resembles what's lately been called vibe coding. I read and assess every line the AI produces, and a fair amount of it gets sent back. Where my time actually goes may surprise people: most of it is spent designing architecture and tests. That is still authoring the code; it's authorship conducted at another level, and with full control. The expensive work is deciding what a subsystem means, what its boundaries are, and what a test must pin down before implementation is allowed to exist. Once that's settled, the implementation is close to determined, whoever or whatever types it in. The proportions of the codebase reflect this: there's considerably more test code than production code, roughly 1.8 to 1, and coverage is greater than 96.5 per cent.

Those constraints are served mechanically. The Librarian, the RAG system that answers questions on the Documentation page, has a second life: it runs as an MCP server during development, giving Claude Code live access to the entire documentation corpus. When the AI needs to know how the timewalker treats grace notes at a measure boundary, or what the plugin boundary permits, it queries the Librarian and receives the relevant ADRs and guides as authoritative context. The same corpus that explains Ooloi to you constrains the AI that builds it.

This has a consequence I didn't fully anticipate: the documentation stays true because it has to. If an ADR is wrong or stale, development goes wrong quickly, and the error surfaces as failing tests or incoherent code. Documentation that governs the implementor can't quietly drift from the implementation. What you read on this site is the operating specification of the running system, kept honest by daily use.

There's a question people are too polite to ask directly: if an AI writes the code, whose work is this? Museums have quietly answered a version of it. Paintings once attributed to Rembrandt alone now carry labels reading 'Rembrandt and workshop', and the label is honest about how such workshops functioned: a workshop hand paints the drapery, the background, the apples in the still life, so the master can concentrate on what needs him. Nobody concludes from this that the disciple composed the picture, and nobody asks whether the master painted it or merely supervised the vibes. He painted it. He could have painted the apples too; it would simply have taken longer. The AI is the disciple here, and the apples are very well painted. The composition, the light, and the decisions about what the painting is remain where they always were.

The apparatus makes this verifiable rather than merely claimed. The instructions, prompts, and skills the AI operates under show exactly what it was given, and by extension what it wasn't. Anyone reading them can see where the authorship sits: in the ADRs, the semantic decisions, the test specifications, the boundaries. The AI implements a design it had no hand in choosing. I'd rather demonstrate that than assert it.

Which brings me to the point of this post. When the source is released, the whole apparatus goes with it. The Claude Code instructions, the prompt files, the skills, the MCP configuration, the tooling that builds the Librarian's corpus: all of it, unsanitised, part of the repository like everything else. Anyone who clones Ooloi can work on it with the same assistance I have, constrained by the same documents, checked by the same tests. There's no private layer where the real knowledge lives.

The reasoning is the same as it's always been. The ADRs externalise why decisions were made. The guides externalise how the systems work. The blog externalises when and in what order. The collaboration itself was the one remaining dimension that existed only on my machine, and I see no reason it should. A project whose development method is reproducible by a stranger is a different kind of open than one that merely publishes its source.

I've watched a notation program die because everything that mattered about it lived in people's heads, and when the people were scattered, the program was over regardless of who owned the code. Every structural choice in Ooloi is a refusal to repeat that. The documentation, the tests, the Librarian, and now the development apparatus itself all point the same way: anyone with the repository has everything, including the means by which it was made.

Ooloi is not designed around my presence, but around my absence.

The pattern is this. When the library changes on the backend, the server broadcasts a notification that any copies 'out there' are now stale. Clients that receive it mark their local cache stale. If the Instrument Library window happens to be open, they fetch immediately and re-render. If the window is closed, nothing happens until it opens – at which point the fetch occurs and the window renders from fresh data. A client that never opens the window pays no cost at all, even if the library is modified repeatedly during the session by other clients. 
​
The sending client follows the same path as everyone else. It does not update its local state from the success response; it waits for the event it will receive as a subscriber, then fetches like any other client. There is one code path for state updates regardless of where the change originated.

Working through the implementation surfaced several problems, each with a clean answer. Two users editing the library simultaneously must not silently overwrite each other's work, so a change is rejected if someone else updated the library first – the conflict is surfaced explicitly, and the second user reapplies their change on top of the current state. Instruments deleted by the user must stay deleted across application updates that ship new default entries, which requires tracking deletions rather than simply omitting items. Display order within a family must survive both user rearrangement and future additions from updates, which requires ordering to be stored explicitly rather than inferred from position.

What the exercise confirmed is the value of the division of concerns itself. The backend stores state, enforces consistency, and broadcasts invalidation events. The frontend gets the data when required, transforms it locally through whatever editing operations the user performs, and submits the result. The backend does not participate in editing decisions; the frontend does not manage persistence concerns.

That division – established here on clean, self-contained ground – is the same division that will govern every piece of rendered state going forward. The Instrument Library is the first authoritative backend entity that is not a piece; its clean behaviour under load, concurrency, and updates confirms that the model generalises. Everything built on top of it will follow the same pattern.

Read all about it in ADR 0045: Instrument Library.

The documentation has accumulated to the point where it doesn't naturally sort itself for a first reader. Architecture Decision Records are numbered chronologically — in the order decisions were made, not in the order you need to encounter them. Reading straight through means confronting distributed-systems reasoning before you know what a `Piece` contains. The answer keeps arriving before you've understood the question.

There's now a guided path that reorganises the material by conceptual dependency: nine phases, starting with motivation and working through data model, language choices, addressing, pitch representation, the plugin system, rendering, and the frontend. Each phase builds the vocabulary the next one requires.

Think of it as an adjunct to the Librarian — where the Oracle answers specific questions, this path builds the context that makes those answers land correctly. It's now the canonical entry point to the technical documentation. It's here.

Musical scores are full of repetition. In a symphony, middle C can appear thousands of times, quarter notes dominate, and the same staccato mark is scattered across every instrument. Most notation software allocates a separate object for each of these occurrences. That means thousands of identical objects, all taking memory and I/O bandwidth for no reason.

Ooloi doesn't.

With ADR-0029, we have implemented selective hash-consing: identical immutable musical objects are represented by the same instance. The same C4, the same staccato, the same quarter note: one object, shared system-wide.

Finishing the statistics infrastructure naturally led to thinking about the next architectural milestone: the rendering pipeline. This is the mechanism that determines what happens when someone clicks into a score to add a note, and how that change propagates through the system.

The design is complete. That in itself is an important milestone, as this is the very foundation on which Ooloi's performance ultimately depends. Everything hinges upon it.

Traditional notation software recalculates entire scores when a single element changes. Dense passages in works like Strauss's Elektra bring systems to a halt because every operation is sequential and single-threaded. The reason for this is that parallelism is very difficult to do with mutable state, which is the traditional approach. Scalability often becomes an issue, with diminishing returns as a result.

Ooloi takes the opposite approach and chooses the Clojure way instead, with immutable state. With this, it is comparatively easy to distribute formatting work across all available CPU cores and use them fully and linearly.

Every user action – whether adding a single note or adjusting spacing – thus becomes part of a coordinated cascade where each stage can run in true parallel across all available cores.
​
The goal is straightforward: responsive editing even in the heaviest repertoire.

ADR-0028 specifies the pipeline in five stages, separating connecting from non-connecting elements and applying a clear fan-out/fan-in pattern.

1. Minimum Widths (Fan-out): Each measure independently calculates spatial requirements – collision boundaries only. Results are immutable and persist until the content changes.
2. Vertical Raster (Fan-in): The MeasureStackFormatter collects widths, generates result rasters, and records both minimum and ideal widths. This prepares the ground for spacing optimisation.
3. Non-Connecting Elements (Fan-out): Independent symbols – noteheads, accidentals, articulations, dynamics – are prepared in parallel. They don't need finalised atom positions.
4. Discomfort Minimisation: Iterative optimisation adjusts widths and system breaks to reduce proportional distortion. No layout changes occur after this stage. From here on, positions are fixed.
5. Connecting Elements​: Slurs, ties, beams, hairpins, and glissandi are drawn only once final positions are known. Sequential coordination ensures continuity across measures and systems.

This separation allows Ooloi to exploit parallelism where possible and enforce order where necessary.

Formatting in Ooloi is plugin-driven. Core elements such as notes and beams are implemented through the same interfaces available to extensions.
​
Plugins can participate in different stages depending on their needs:

• Spacing hook (Stage 1) for collision boundaries
• Paint hook (Stage 3) for independent elements
• Connect hook (Stage 5) for elements spanning multiple atoms

Simple articulations may use only the first two; beams may require all three. This uniform model ensures extensibility without compromising performance.

The optimisation engine measures deviation from ideal proportions across measures, systems, and pages. Improvements multiply: small gains in multiple places compound into significant overall reductions. Hard constraints such as manual breaks provide natural stopping points.
​
This replaces arbitrary iteration limits with a principled measure of quality.

Claypoole provides efficient thread-pool execution, delivering significant speed-ups over built-in Clojure parallelism. STM transactions keep operations atomic while allowing concurrency inside each stage. Cooperative cancellation ensures that rapid user input remains responsive.
​
The system treats a single user as a 'collaboration network of one'. The same infrastructure that supports multi-user editing ensures smooth interaction for individuals.

This pipeline is the structural core that should make scrolling through Elektra or Ligeti's Requiem as fluid as editing a Gnossienne by Satie.
​
The specification is complete. Implementation begins as soon as the current phase closes. Ooloi's promise of responsive, professional-scale notation depends on it.

​Scary stuff.

​Full specification: ADR-0028: Hierarchical Rendering Pipeline with Plugin-Based Formatters

Yesterday’s post was about pitch transposition in Ooloi: how an old Igor Engraver function (printed on a t-shirt, of all places) came back to life in a new context. That work didn’t just solve the mechanics of shifting notes up and down; it reopened the larger question of playback. How do you hear microtonality and advanced humanisation without drowning in technical workarounds?

In Igor, the answer was MIDI. Notes were split across channels, bent into place, reassigned constantly. The result worked, but at the cost of complexity: a “DNA soup” of allocations and pitch-bend tricks. Ingenious, but exhausting.

Ooloi makes a different choice.

With ADR-0027: Plugin-Based Audio Architecture, we draw a line: no MIDI output in the core, no audio generation in the backend. Playback is done entirely through plugins in the frontend. If you want VST/AU instruments, SoundFonts, OSC, or any other output path, you install a plugin. The backend remains what it should be: musical data, collaboration, structure.

This is not just simplification, it’s liberation.

• Microtonality is handled directly in the data model, then played back by plugins without channel gymnastics.
• Humanisation is no longer bound to 7-bit controllers; plugins can drive modern sample libraries with full parameter precision.
• Collaboration becomes clearer: the backend never streams audio, never mangles MIDI, never compromises. Each client handles its own sound.

Put bluntly: we no longer need MIDI as an output protocol. It served its time. For professionals who need nuanced playback, orchestral realism, or contemporary techniques, we now have better tools: VST/AU plugins and beyond.

That said, MIDI output isn’t forbidden. If anyone needs it, a frontend plugin can provide it. For tonal music it will work fine. But if you want advanced humanisation or microtonality, you’ll inherit the need for all the old machinery: channel allocation, pitch-bend acrobatics, the DNA soup. That’s exactly why Ooloi itself doesn’t touch it.

The logic is simple: Ooloi’s core manages music, not sound. Plugins handle playback, and in doing so, they do it better than MIDI ever could.

The DNA soup is gone. What remains is clean, modern, and far more powerful.

Ooloi is moving fast. Architectural decisions, implementation milestones, and the long road toward open-source release deserve a channel that isn’t buried in blog posts or scattered across updates.

The Ooloi Newsletter is that channel. It’s for composers frustrated with the lag of existing software, musicians curious about what modern architecture makes possible, educators and publishers planning future workflows, and developers who want to see Clojure’s STM, transducers, and gRPC applied directly to real musical problems.

This isn’t marketing. There’s nothing to hype, no metrics to chase. It’s progress – the daily work of turning musical thinking into software design. Updates arrive when there’s something real to report: once or twice weekly in active phases, slower during architectural deep work.

Expect honest accounts of what’s been built, what broke, and why decisions were made. Technical when it illuminates music, musical when it drives architecture. No jargon for its own sake, and no dumbing down.

If that sounds useful, subscribe at buttondown.com/ooloi.

The thread from FrankenScore to Ooloi continues. You’re welcome to follow it.

The Ooloi server must of course also have comprehensive introspective statistics, as it can be deployed in several ways and has a structure which is perhaps a bit unusual. The combination of STM-wrapped gRPC API calls with server-to-client event streaming creates some operational challenges: things like per-client queue overflow behaviour and collaborative editing session patterns.

Hence this new ADR on server statistics, which takes a two-level approach: server-wide aggregates that survive client churn, plus detailed per-client metrics for operational visibility. Oh, and it interfaces with Grafana, Prometheus, and friends straight out of the box via simple HTTP endpoints.

Halfway through the stats implementation now. It's been a productive weekend.

Right. Quick update from the development trenches.

When I completed Ooloi's backend engine in July, starting work on the frontend interface revealed the anticipated cascade of architectural requirements that needed systematic resolution first.

Here's what emerged, in order:

1. Collaborative Undo/Redo Architecture (ADR-0015)
Thinking about frontend-backend relationships immediately raised the question: how does undo/redo work in a multi-client, distributed collaborative setup? The answer required a three-tier architecture separating backend piece changes (coordinated via STM) from frontend UI changes (local to each client).

2. Universal Settings Architecture (ADR-0016)
The insight that there should be no global application settings, only per-piece settings living inside each piece, led naturally to implementing settings not just on the piece level, but across all levels of the hierarchy. Any entity – piece, musician, staff, pitch – can now have configuration attributes via a unified defsetting macro with lazy storage and automatic VPD support.

3. Component Lifecycle Management (ADR-0017)
Multi-scenario deployment demanded rock-solid system architecture using Integrant. This needed to be in a stable architectural form – wiring, lifecycle boundaries, failure modes – before setting up the actual components with proper dependency injection, partial failure handling, structured error codes, the full production suite.

4. Automated gRPC Generation (ADR-0018)
With component architecture sorted, I could tackle the actual gRPC implementation: automating API endpoint generation for native Java interop across hundreds of methods, plus bidirectional communication for real-time collaboration. Manual implementation at this scale would be architecturally impossible.

5. In-Process Transport Optimisation (ADR-0019)
Combined deployments (frontend and backend in same process) were using unnecessary network transport. Implementing automatic in-process gRPC transport delivers 98.7–99.3% latency reduction whilst preserving external monitoring capabilities.

6. TLS Infrastructure (ADR-0020)
Secure connections are essential for distributed deployments – conservatory intranets, corporate environments, cloud SaaS situations. Auto-generating certificates with full enterprise capabilities makes this transparent whilst supporting everything from development to production.

7. Authentication Architecture (ADR-0021)
Finally, distributed deployments require comprehensive authentication and authorisation. Pluggable JWT-based providers scale from anonymous sessions to enterprise LDAP integration. This is fully designed and will be implemented as deployment scenarios require.

Current Status: About 95% of the above is implemented, tested, and production-ready.

Next Steps: Finish the auto-generated gRPC Java interop interface, then create an actual frontend client of the 'Hello World' variety and ensure it runs and communicates across all deployment scenarios.

The rather encouraging discovery throughout this process was how readily the existing functional architecture accommodated these enterprise concerns. Vector Path Descriptors naturally supported universal settings. STM transactions elegantly handled collaborative undo operations. The component system absorbed authentication providers without strain. When features like collaboration or security slide cleanly into place, it's not luck – it means the architecture wanted them there. That's what sound foundations do.

Worth noting: collaboration isn't something tacked on later. It's integral to the architecture from the ground up.
​
Right. Back to the gRPC generator.

​I've been saying I'm itching to open source Ooloi, but waiting for the complete software felt increasingly artificial. The documentation tells the real story – twenty-five years of architectural evolution from Igor Engraver through AWS systems thinking to this closure in Clojure.

So here it is: the complete Ooloi documentation collection, released publicly ahead of the software itself.
What you'll find:

• Comprehensive guides teaching advanced Clojure through musical problems
• Complete architectural decision records showing our thinking
• The timewalker guide (with three Rocky Horror references, naturally)
• Real functional programming education through meaningful domain examples

This represents my attempt to walk the talk after critiquing FP drawbridge syndrome. These guides serve dual purpose: they document sophisticated music notation architecture whilst teaching functional programming concepts through examples that actually matter.

The timewalker guide alone demonstrates transducers, lazy sequences, and functional composition through orchestral score traversal. The polymorphic API guide teaches multimethods through musical type systems. The concurrency patterns show STM coordination through collaborative editing.

Twenty-five years of thinking, distilled into something that I hope proves useful beyond music software. The architecture is complete; the foundations are solid. Now you can see why I've been eager to share this work.

An organism evolved, indeed.
​
Explore the complete documentation: https://github.com/PeterBengtson/Ooloi-docs

​/Peter

An Architecture Decision Record (ADR) is a point-in-time document that records architectural decisions and the reasoning behind them. And since communicating architectural ideas clearly to collaborators is extra important in open-source, I've just added a bunch of ADRs to the Documentation page.​

​They cover various aspects of the FrankenScore architecture, from high-level design decisions to specific technical choices. They are:
​

• ADR-0000: Choice of Clojure as the Primary Programming Language
• ADR-0001: Separation of Frontend and Backend into Distinct Clojure Applications
• ADR-0002: Adoption of gRPC for Communication Between Frontend and Backend
• ADR-0003: Integration of Plugins as a Core Architectural Component
• ADR-0004: Implementation of Software Transactional Memory (STM) for Concurrency
• ADR-0005: Selection of JavaFX and Skija for the Frontend GUI
• ADR-0006: Adoption of SMuFL (Standard Music Font Layout) for Music Notation
• ADR-0007: Implementation of Nippy for File Persistence
• ADR-0008: Implementation of Vector Path Descriptors (VPDs)
• ADR-0009: Implementation of Real-Time Collaborative Features