Why#
Every project has assumptions. Most of them are never written down. They live in the builder’s head, applied inconsistently, invisible to anyone else — and sometimes invisible to the builder too. A decision made in week one shapes what is possible in week ten, but without documentation, the connection is never made explicit. You just find yourself constrained in ways you cannot fully explain.
HomeStack started with a strategic framework before a single service was running. Ten principles, six pillars, four goals. Written down, argued through, ordered by priority. The document was called the constitution — the thing everything else would be tested against.
Version 1.0 was written in early April 2026. It had fourteen principles and thirteen pillars. It was thorough in the way that early project documents often are: comprehensive, a little redundant, trying to cover every case before the cases had actually occurred.
Version 2.0, written two weeks later on April 18th, cut it in half. Ten principles, six pillars. Not because the thinking had changed, but because the early version had confounded principles with procedures. A principle is a value — something that holds regardless of how the technology changes. A procedure is how you implement it today. Mixing the two produces a document that becomes outdated the moment anything changes and that nobody reads.
The revision was also about honesty. Some of the original fourteen principles were aspirational rather than commitments. Version 2.0 kept only what could actually be tested. If a decision could not be evaluated against a principle, the principle was either too vague or not really a principle.
Family#
The constitution is not a document the family will ever read. It exists for one person — the builder — as a check against drift. The question it answers is not “what do I want to build” but “how do I know if I am building the wrong thing.”
Principle one is the most important one for the family: usability is the highest priority. Complexity belongs to the builder, not the user. If a technically better solution is harder to use, the technique loses. This sounds obvious. It is surprisingly easy to violate when you are deep in a problem and the elegant solution requires the user to understand something they should not have to understand.
Principle four is the one that matters when things go wrong: recoverability. A backup that only the builder can restore is not a backup. The documentation must be clear enough for a family member, or an outside expert, to follow without help. This is harder than it sounds. It requires writing for a reader who does not share your assumptions — which is a different kind of discipline than writing for yourself.
Tech#
Three documents govern HomeStack, and all three were established on April 18th — the same day as the strategic framework revision.
The first is the constitution itself: why and what. Principles, goals, the values that do not change when the technology does.
The second is the architecture document: how the system is designed to work, the decisions that shaped it, and the reasoning behind those decisions. It sits between principle and practice. A strategic principle says “data must be recoverable without the builder.” The architecture document says which database engine is used, why PostgreSQL was chosen over alternatives, what the backup strategy looks like in practice, and what exceptions exist and why. Without it, the gap between principle and practice is invisible — you know what you want and you know what you have, but you cannot reconstruct why the system is built the way it is, which means you cannot change it intelligently.
The architecture document started on April 18th and will be revised continuously. An architecture document that never changes is either describing a system that never changes — unlikely — or it has been abandoned as a living reference and become a historical artefact.
The third document is the baseline: a snapshot of the actual running state on a specific date. Every service, every version, every open risk. Not aspirational — actual. The value of a baseline is that it makes drift visible. When something breaks six weeks later, the baseline is the reference point. What changed? When? Why? Without it, troubleshooting is archaeology.
The first baseline covered what existed at the time: Ubuntu Server 24.04, Docker with three bridge networks, Caddy as the reverse proxy, PostgreSQL as the primary database, SSH hardening, UFW, Fail2Ban, AIDE, BorgBackup. No external services yet. No SSO. No monitoring beyond Uptime Kuma. A short document — deliberately. A baseline that tries to describe everything becomes a burden to maintain. A baseline that describes the actual current state, updated after each significant change, becomes a tool.
Project#
Three documents, one day, before most of the stack existed.
The instinct to write the framework first rather than last is worth examining. It is not obviously correct. You could argue that you should build first and extract principles from what you actually did. That approach produces principles grounded in reality but tends to produce post-hoc rationalisations — stories that justify what happened rather than tests that would have changed behaviour.
Writing the framework first, then revising it when it proved too abstract, produced something different. The first version exposed the assumptions. The revision made them honest. The result was a document that could actually be used to make decisions — not just to describe them after the fact.
The architecture document and the baseline are the complement. The framework says what matters. The architecture says how it is built and why. The baseline says what exists. Together they answer a question that most projects never ask clearly: does what we have match what we said we were building?
For HomeStack on April 18th, the answer was: partially. The foundation was sound. The services were not yet built. The principles were written. The practice was ahead of them.
That gap is not a problem. It is a plan.