The other half of the software factory

Software factories are back in my feed, and the argument is the one I thought we had settled twenty years ago.

Between 2000 and 2020 offshore development promised businesses cheap custom software, and what they often got was cheap software. The quality problems were real, and the answer the industry found was not to shout at the suppliers but to make coding, testing and deployment mechanical: boring, repeatable, and checked by a machine rather than by a hero.

That part is done. A linter runs on every commit, a test suite runs on every push, a pipeline builds, signs and releases, and a fleet pulls its own desired state from a repository. In our own shop a release is a tag, a deploy is a reviewed commit, and nobody logs in to a box to restart anything. None of that is clever any more, which is the highest compliment engineering can pay a practice.

That is half of the problem, and it is the half that was always going to yield to tooling, since it is about how code is handled rather than about what the code does.

The half that does not yield to tooling

The other half is the functional one: deciding what the software should do, and writing it so that the decision survives contact with a team, a successor, or now a coding agent. You cannot make that mechanical by buying a tool, but you can make it mechanical by changing the shape of the work, and three practices do it together. Some people have started calling the combination EVE, and I will use the name.

Event storming comes first. Before anyone draws a database, the people who know the work stand at a wall and name what happens, in the past tense: a member registered, a book was procured, a reading finished. The orange notes on that wall are the vocabulary of the business and nothing else, and the commands that cause them and the rules that react to them are added only once the events are agreed. Anyone who runs the club could read that wall, which is the test it has to pass, since the owner of the business will be reading it too.

Vertical slicing decides where the code lives. One capability, one folder, and everything that capability needs inside it: the command, the event it produces, the rule that decides, and the door the outside world knocks on. Not a folder of controllers and a folder of services with the feature smeared across both, but one folder called register_member that contains the whole of registering a member.

Event sourcing decides what the state is. The state of a club is not a row that gets overwritten but the list of what happened to it, in order, and any table you need for reading is built from that list afterwards, by a separate part of the system that only writes tables, and read by a third that only answers questions. Writing, recording and answering are kept apart on purpose, which is the CQRS part of the name if you like acronyms, and which means each part can be small and dull.

Put the three together and the code that comes out is boring and predictable, and I mean that as praise. The same shapes repeat. In the book club below a desk is four files, an event is one module, a projection is one event to one table, and a query is one question with one answer. That is the property that matters for a factory: when the shapes repeat, they can be produced by a template or by a language model, and checked by a machine.

What a stranger sees

Here is a book club, built this way, with the code public. There are three applications. The first holds what the club can do: initiate a club, register a member, procure a book, start and finish a reading, plan a party, archive the club. The second is organised around the events, one folder per event, each turning it into rows in the tables the third app reads. The third answers questions: a book, a member, a reading, by id.

Open the first folder and you can read the process of running a book club without opening a file. You can also read a policy as a sentence, since one folder is named after it: on member registered, maybe plan a party. And you can tell which three facts the club shares with the outside world, since those folders start with emit. That is screaming architecture: the names say what the code does, not how, and the structure is the documentation. We call it the stranger test. A stranger opens the repository and tells you what the business does, and if they cannot, the names are wrong.

Those three folders are also the whole of the club's public contract, and the only thing anyone outside the club can depend on. The nine events inside are ours to change. A fact that has left the club is not: its version is in its name, a published version never changes and never disappears, and when the club has more to say it publishes a _v2 next to the _v1, which is the open/closed principle applied to a contract. Who consumes a fact is not the club's business, and that is the point of publishing facts rather than calling consumers: the club keeps no list of them, cannot break them by accident, and does not wait for them when it ships. Who owns the club is equally short. One division, one repository, one owner, and a person's yes before anything reaches main.

Onboarding changes character when the test passes. A new colleague reads one folder and owns one capability by the afternoon, and a coding agent, which is the newest colleague in every shop now, reads the same folder and produces the next one in the same shape, because there is only one shape to produce.

The same club, walked through from the wall to the stored event, in sixteen minutes:

Five Ds, with a nod to four Cs

Simon Brown's C4 model gives architects four zoom levels for drawing a system: context, container, component and code. It is good and we use it. For the process side we name five levels of our own, all starting with D, partly as a wink to C4 and partly because the fifth one is the point.

A Domain is the whole business endeavour. A Division is one cohesive piece of software inside it, the bounded context, the thing that gets its own repository. A Department is one of three roles inside a Division: commands, projections, queries. A Desk is one capability inside a Department, the folder you saw above and the atomic unit of work. And the Dossier is the aggregate: the folder of event slips that passes from desk to desk and grows as it goes. C4 tells you where the boxes are, and the fifth D tells you what moves through them.

The desk is also why the factory idea stops being a metaphor. A desk is small enough to describe on one sticky note, strict enough to template, and complete enough to test on its own. Give one desk to one person or one agent as a work package, ask for the failing test first, have a second pair of eyes pass the change, and let a person say yes before it reaches main, and you get the same quality from the tenth desk as from the first. If a desk is a unit of work it is also a unit you can price, which is where I want to take this.

The first storm

Granted, the first storm is the hard part, and no factory removes it. Getting the right people in front of the wall, naming the events honestly and finding where one division ends and the next begins is thinking, and it stays thinking. What the method does is make everything after the wall boring, so that the thinking is the only thing a person has to spend attention on.

The book club above is our teaching repository, in Erlang, which is one language and not the one most readers write in. The rules it follows live in a public corpus, with the naming rules, the templates, and a long list of the mistakes we made and wrote down so we would not make them twice. The crew of coding agents that builds this way is called Martha, and it still needs a person to say yes before anything reaches main.

The first half of the factory is a product you can buy. The other half is a way of working, and it is the half that decides whether the code an agent writes tomorrow is something you can still read in five years.

Would you let a factory like this build your next system, and if not, which half worries you?