02 · The boundary: files and database

The most important decision in this project is also the simplest to describe: content lives in files, reader data lives in the database. That line has not moved once through the whole of development, although almost everything around it has changed.

An entry is a JSON file in the repository. It has a title, a date, a series, an author and an array of paragraphs. Nothing more. Several things follow that cannot be bought at any price: the full change history of every text, the ability to undo an edit from months ago, a diff review before publishing, and a backup of the entire body of work on every machine where somebody once cloned the repository.

Comments, ratings, view counters and the event log go to the database, because they are data the author does not write — they come into being while people read, and they have no business requiring a deployment in order to appear.

The question came up once whether comments could be files too. The answer is architectural rather than aesthetic: an edge runtime has no writable file system. Not “we advise against it” — there is simply nowhere to write. That single property of the platform forces a split that would have been right anyway.

The side effect turned out to be worth more than the intended effect. Since content is files and the engine merely looks for them by a fixed pattern, swapping the content directory yields a different site on the same code. The whole later productisation grew out of a decision made in the first week for an entirely different reason.