The Engine Owns the Model

"One writer, many readers — and the writer is the engine."

Producer and Consumers

Track 3 said there's one model. This track says where it lives and who's allowed to touch it. The answer: the engine produces and owns the music model. Everyone else — the UI, the Sidekick, any future bridge — is a consumer that receives the model through the API. The engine writes; clients read. That single ownership line is what makes the model trustworthy: there's exactly one place it can be created or changed.

What the API Surface Looks Like

Concretely, the boundary is a small set of endpoints. You hand the engine audio and it does the analysis (owning the resulting model); you ask for a track and it hands you the model; you ask for an easy-mode version and it computes and returns a new model. Nothing on the client side ever reaches past these endpoints into the engine's guts.

Ember's Pattern, Transplanted

This isn't a new invention for Bonfire — it's lifted directly from Ember. Ember owns image generation and exposes an API that Cinder consumes; Cinder never imports Ember's sampling internals. Bonfire owns music analysis and exposes an API that its UI consumes; the UI never imports the engine's analysis internals. Same shape, different medium. The reason it's worth copying: an engine with a clean API boundary can feed consumers it hasn't even met yet (Rule 2 — cost absorbed downstream, not pushed up).

Code

The API surface — engine owns, clients read·bash

# Engine analyzes and OWNS the resulting model:
POST /api/v1/tracks                      # upload audio -> engine builds the model

# Clients READ the model through the API:
GET  /api/v1/tracks/{id}                 # receive the music model
GET  /api/v1/tracks/{id}/audio           # the decoded audio for the waveform
GET  /api/v1/tracks/{id}/easy?level=1    # engine computes a NEW (simplified) model

# The built-in UI hits these same endpoints.
# It never imports the engine's internals.

Exercise

For any app you've built or used, identify the single 'owner' of its core data and list who else reads it. Then ask the dangerous question: can any reader also write? If a reader can mutate the core directly (not through the owner's API), you have multiple writers — and that's where trust in the data breaks down.

Hint

Multiple writers is the smell. If two code paths can both change 'the truth,' you can't trust either. Funnel all writes through one owner and the data becomes something readers can rely on.