Same-Process Is No Excuse

"The UI and the engine share a process. That's a convenience, not a license to skip the API."

The Tempting Shortcut

Bonfire's built-in UI and its engine run together — one server, the engine on a port, the UI talking to it. Because they're so close, there's a constant temptation: why fetch the model over HTTP when the engine object is right there in the same codebase? Just import it. It's faster, it's fewer lines, and in the moment it works perfectly.

It also quietly destroys the thing that makes the engine worth building. The instant the UI imports engine internals, it's coupled to the engine's shape, not its API. Refactor the engine and the UI breaks in ways the API contract never promised. Worse, the model can now arrive at the UI by a path no other client can use — so the Live bridge, the mobile app, the CLI you build later are all locked out of that path.

Treat In-Process Like Remote

The discipline is simple to state and annoying to hold: the built-in UI calls the API as if the engine were on another machine. Even though a function call would work, you make an HTTP request. The cost is a little latency and a little ceremony. The payoff is that the UI proves, on every single request, that the API is sufficient — because the UI is living proof that a client can do everything it needs through the API alone.

Code

Same-process is not an excuse to skip the API·typescript

// WRONG — the built-in UI importing engine internals:
import { MusicModel } from "../../backend/model";  // coupling!
const song = MusicModel.load(trackId);             // a path no other client has

// RIGHT — the UI calls the same API a remote client would:
const song = await fetch(`/api/v1/tracks/${trackId}`)
  .then((r) => r.json());

// If the UI can ONLY reach the model through the API,
// a future Live bridge gets the identical surface for free.

Exercise

Find a place in a project where two parts share a process and one reaches directly into the other (a shared import, a global, a direct DB read). Ask: if these two were on different machines, what API call would replace that reach? If you can't name the call, the boundary doesn't exist yet — and a future third party can't be added without inventing it.

Hint

The test is the 'different machines' thought experiment. Anything that only works because two parts happen to share memory is a coupling that an API boundary would have to replace anyway. Better to draw it now.

The Tempting Shortcut

Treat In-Process Like Remote

Code

External links

Exercise

Progress

Comments 0