System

How a system is built: the history of actions, a command above and its records under it; and a system as commands, each run like a function, a system above calling them. Research still: these rules settle here, apart from the rules of the code.

9 rules·2 groups·2 sources

9 rules

ALLAt a glance

HISTThe history of actionsA command above, its records under it.

HIST-01

Every model writes three kinds of record: created, updated, deleted. One row per change in the database, named after the model, post_created; no other kind at this level: publishing a post is a command, api2_publish_post, and its record is post_updated.

history.md
Left, post_published crossed out as a fourth kind; right, post_created, post_updated and post_deleted, and api2_publish_post as a command with post_updated under itLeft, post_published crossed out as a fourth kind; right, post_created, post_updated and post_deleted, and api2_publish_post as a command with post_updated under it
HIST-02

Every record points up to its command, named by its entry point. The call that caused the change is written first, api2_create_project, api2_publish_post; each record it causes carries its id.

history.md
api2_create_project with project_created and folder_created under it; stored as three rows, the two records pointing up to #1api2_create_project with project_created and folder_created under it; stored as three rows, the two records pointing up to #1
HIST-03

Two levels, always. Under a command only records: never a record without one, never a command under a command.

history.md
A record under an empty place and a command inside a command, crossed out; a command with its two records under itA record under an empty place and a command inside a command, crossed out; a command with its two records under it

CMDA system as commandsSmall commands, each like a function; a system above calls them.

CMD-01

A system is its commands first. Each thing it does is one command: a name, an input, an output; it starts, does its work and ends; run, read and debugged alone.

commands.md
Left, one big app, its parts tangled, to change one thing read all of it; right, six small commands, each with what it takes and returns, under the system above that calls themLeft, one big app, its parts tangled, to change one thing read all of it; right, six small commands, each with what it takes and returns, under the system above that calls them
CMD-02

The app above calls the commands; they never call one another. It picks a command, packs its arguments, calls it and passes the result on. A command takes its arguments, runs as often as needed, and is read apart from the rest.

commands.md
Two chains: transcribe, voice.txt, summarize, summary.json, aloud, reply.mp3, with transcribe calling summarize crossed out; run-build, the CI, refresh-builds, builds.json, the Builds page; above each command what starts itTwo chains: transcribe, voice.txt, summarize, summary.json, aloud, reply.mp3, with transcribe calling summarize crossed out; run-build, the CI, refresh-builds, builds.json, the Builds page; above each command what starts it
CMD-03

Every command is drawn. One picture per command, what goes in and what comes out, and one of how they connect; made with the command, kept beside it.

commands.md
An app as its commands by family, refresh, act, make, check and maintain, a card per command with what it takes and leavesAn app as its commands by family, refresh, act, make, check and maintain, a card per command with what it takes and leaves
CMD-04

Any command runs by hand at any time. The system is built on it: called whenever, the command reads the state and does what is left; nothing breaks.

commands.md
refresh-builds called at night, mid-work or twice in a row ends each time; nothing done, it does it all, half done the rest, all done nothingrefresh-builds called at night, mid-work or twice in a row ends each time; nothing done, it does it all, half done the rest, all done nothing
CMD-05

The pages that depend on a command know it runs. They show its progress from the file it writes, and offer to start it again.

commands.md
refresh-builds writes progress.json; the Builds page reads it and shows the run in progress, 2 of 3, with a Restartrefresh-builds writes progress.json; the Builds page reads it and shows the run in progress, 2 of 3, with a Restart
CMD-06

A command that runs one at a time guards itself. A second call sees the first and ends with an error that says so; the caller need not think of it.

commands.md
The first call takes its lock and runs; a second call meanwhile ends with already running, the first call holds the lock, exit 1The first call takes its lock and runs; a second call meanwhile ends with already running, the first call holds the lock, exit 1