or, most of what we build is plumbing
I build software for people who have to get work done together. A booking board. An allocation system. A planner, an ops console — the kind of thing where two people are looking at the same screen at once and it has to be true for both of them.
That sounds like a lot of different problems. It's one, wearing hats. What a person sees is a document: a composed shape, gathered from tables that know nothing about screens. Keeping that document truthful while several people write to it — without re-fetching the world, without losing what someone was halfway through typing — is most of the work. It is also almost none of what your framework helps with.
So the practice has two halves. One is the apps, built for the people who use them. The other is a run of small tools, each an attempt to say the problem more exactly than the last. There have been rather a lot of them. We'll come to that.
Start from what someone sees in order to do a job. Not from the tables. Do you draw the schema first? Most of us do, and then spend the rest of the project bending screens around it. A document is what a person watches while they work, and the entities fall out of that — the other way round from how it usually goes.
Tell it as stories. An actor and an action, in a sentence a customer can call true or false. Femi picks the sea bass, and the couple's list shows it. If a story describes the interface moving rather than what somebody wanted, the feature was invented first and justified afterwards. The model is finished when every record traces back to something a person said they do.
Prove it before building it. A model can be checked — that everything is reachable, that every write an actor can make echoes back into something they are watching, that no screen asks for a permission nobody grants. Six of those run after every change in hjeli. What's missing gets named on a Tuesday, rather than discovered in week six.
Then the build is a transcription. If the judgement is done and written down, making the code is the easy part — and it can be done again, on another substrate, without having the argument twice.
A year of clean rewrites, each chasing the same idea until it got small enough to hold: from dzql, which named the problem and couldn't finish it, to eta, where the whole app is documents, every write is a patch, and every patch knows its own inverse — so undo costs nothing, and the wire is legible enough to read in a terminal.
Eight rewrites in a year. Wasteful? I'd have said so too. But nothing survived a rewrite that hadn't earned the trip, and the last one is four thousand lines. How that last one was made — four days, sixty-four releases, and a review that graded it D — is a story of its own.
Under all of it is Bun, which does more than most projects ask of it. paintbrush shows how much: bun create blueshed/paintbrush myapp gives you a website of routes and resources and very little else. Open it in two windows, edit the message, and the save shows in both. Bun is the server, the bundler and the test runner, and it has a WebSocket, SQLite and S3 built in. The tests drive a real browser and fail below 100% coverage, and the deploy to Railway is written as code.
It is a hello world, and the way on. A resource starts as two HTTP routes. It becomes a delta document when several people edit it at once, and an eta app after that, and the page's code keeps its names all the way up.
Twenty-three technical articles, 2021 to 2025 — Postgres doing the work Redis was hired for, async all the way down, stored functions instead of a middle tier, and a recurring argument that the middle of our stack has quietly disappeared.
Each one opens with a photograph of west Wales, which is where I am, and rather a lot of why any of it gets finished. Like this.
blueshed.co.uk is Peter Bunyan.
Before this, back-office architecture for hedge funds, where two systems disagreeing about the same trade is not a thought experiment and reconciling them is the job. The same problem as the rest of this site, with the stakes made obvious.
Earlier still, iChat in Austin, Texas. The protocol for listening that became pears was worked out there in 1995 — and written down properly thirty-one years later. Nobody has ever accused me of rushing.
Write to pete@blueshed.co.uk.