Skip to content

Selected design decisions

I keep decision context so future changes don't re-litigate settled trade-offs.

Status: decision record · checked Oct 26, 2026

In plain terms

These are recorded decisions with rejected options and accepted trade-offs: the reviewer role, no silent fallback to a paid model, a design lock tested against the code, reachability, backups, ownership, and where docs live.

flowchart LR C[The context] --> O[The options, and
why each one lost] --> D[The decision and the
trade-offs accepted] --> RB[The rollback cost,
written down] --> A[Later amendments,
never a rewrite]
flowchart TD C[The context] --> O[The options, and why
each one lost] --> D[The decision and the
trade-offs accepted] --> RB[The rollback cost,
written down] --> A[Later amendments, never
a rewrite]

Decisions are recorded as short ADRs: context, options with reasons for rejection, the decision, the trade-offs accepted, and later amendments. A selection, with environment detail removed.

How decisions are recorded

There are 73 architecture decision records (as of Oct 2026).

  • Options and why they lost. Every record lists the alternatives and the reason each was rejected, because the next person to propose the rejected option should find the argument already made.
  • Trade-offs and the cost of being wrong are written down. The cost of the chosen option goes in the record, not in someone's memory, together with a rollback cost: how hard it would be to reverse, from trivial to touching many systems.
  • Records aren't rewritten or deleted. A record has a status (proposed, accepted, deprecated or superseded). If a decision turns out to be wrong or unimplementable, a later record supersedes it or amends it and points back, so the history shows what was believed when. One example is below.
  • Agents propose; a person approves. The documentation audit looks for decisions worth keeping in the notes agents leave behind and proposes records for the ones not yet captured, but it never writes a record itself.
  • They are checked against the facts. A record is reviewed when it is written, and again when a page that depends on it is verified. The reachability decision below was corrected after someone tested the belief it rested on.

A separate role checks every change, and the author cannot post it

Context. A worker agent merged its own pull request with no review at all (How agent output is trusted).

Option Verdict Why
Ask the author agent to review its own change rejected same context, same blind spots, and nothing stops it skipping the step
A second pass by the same identity in the same session rejected it shares the author's assumptions, and it is still an identity that can merge
A rule in the prompt: don't merge your own change rejected that is a document-level rule; it works until the one time it doesn't
A separate reviewer role, whose result only one identity can post, recorded before it is posted, and required by branch protection chosen branch protection in the main repositories blocks a merge that lacks the reviewer's recorded decision, and the decision is auditable

Trade-offs accepted. Every merge into a main repository waits for the independent reviewer, so merge time has a floor, and reviewer capacity becomes a resource to manage. The reviewer's model is chosen per batch by how risky the change is, and it can be raised but never lowered. Later. A review that only read the change is labeled as such, because reading a change can miss what running it would catch.

No silent fallback to a paid model

Context. The default worker tier is the cheapest one that can do the job. Sometimes it is unavailable, or its allowance for the period is spent, and the work could be done by a dearer model that is available.

Option Verdict Why
Fall back automatically to the next model that is available rejected spend rises without anyone choosing it, and the work is done by a model nobody validated for that lane
Send the needed model through whichever tool happens to be installed rejected it bills against a quota nobody is watching, and drains it silently
Stop, report, and let a person or a dispatch with a written reason choose chosen the cost of a heavier model is always a decision with a reason on record

Trade-off accepted. Work waits. A refusal is an outcome to read, not an error to route around, and I accept the idle time to keep spend explicit (routing agent work by cost).

A design lock tested against the code, and its amendment

Context. Before building the remote dispatch and deploy tiers I recorded a short list of platform-wide design locks: scoped keys per device, a mandatory audit record for every dispatch, guards that enforce and fail closed by default, a two-call confirmation for deploys, signing authority held in one place, and a narrow allowlist posture for what a worker may run.

What I found. I read the worker's code against the locks. One lock said extra capabilities would be granted "per dispatch". The worker intersects a per-host ceiling with each task's own list, so the hub can only narrow what a task may do, and the real unit of a grant is the host.

The amendment. The grant became per host, declared explicitly, read as the statement "this host runs agentic work", and denied by default. The original record stays; the amendment points back at it.

I treat a lock as a claim the code has to back. When the code says otherwise, the record gets an amendment that points back at the original, never a quiet rewrite.

More decisions (infrastructure)

These are about the home-lab infrastructure. Each has its decision in one line here, and the full record opens with a click.

Put reachability at the layer that matches the protocol

Decision. HTTP and WebSocket terminate at the gateway, and non-HTTP stays at the network layer: one rule by protocol type.

Read the full record

Context. Roaming clients needed a file share and a real-time WebSocket service, both on a segmented network. They looked like the same problem but use different protocols. A long-held belief that the application gateway could not reach the second service's origin turned out to be wrong the moment somebody tested it.

Option Verdict Why
Route the WebSocket host to clients at the network layer, like the file share rejected the gateway already owns auth, liveness and fallback
Proxy the file-share protocol through the HTTP reverse proxy rejected it is stateful, multi-port and mounted by the OS, so it isn't an HTTP upgrade path
HTTP and WebSocket terminate at the gateway; non-HTTP stays at the network layer chosen one rule by protocol type, not cosmetic symmetry across resources

Trade-off accepted. Clients get one HTTPS entry point, but the gateway now sits on the real-time data path, and the gateway-to-origin hop becomes a documented dependency that must stay explicitly allowed. Later. Stale documentation asserting the old belief was corrected after the test, and the decision record says so.

Back up by recovery class, and send only the critical tier offsite

Decision. Layers by recovery class: git for code, VM backups for guests, one engine for host state, device exports separate. Only the critical tier goes offsite.

Read the full record

Context. Backups had grown tool-by-tool per host, leaving several deduplication engines and inconsistent secret layouts. Adding offsite object storage was the trigger to standardize the contract without replacing VM-level backups.

flowchart TD G[Git, for code] --> R[(Git remote)] V[VM disks] --> P[(Backup server)] H[Host state] --> N[(NAS repo)] H --> O[(Offsite repo)]
Option Verdict Why
Keep the legacy engine on the bare-metal host only rejected three engines and asymmetric secret layouts at exactly the moment offsite is introduced
Migrate the whole fleet to one engine rejected one host already used the target; full migration cost outweighed the benefit
Layers by recovery class: git for code, VM backups for guests, one engine for host state, device exports separate chosen each layer matches how it will be recovered; one binary and one secret shape for host-level backups
Continue mirroring everything offsite rejected (a later decision) paid duplication of what the NAS already holds; the copy operation can't take a path-level subset

Trade-offs accepted. More timers and roles; operators must tag new data correctly or it stays NAS-only. Later. The legacy engine was decommissioned after a verified cutover, and offsite scope was narrowed by a follow-up decision.

Who may write what: ownership zones on a device that both people and automation write to

Decision. Partition the configuration into zones with a declared owner: code-managed, application-managed and manual.

Read the full record

Context. A network device took configuration from different kinds of writers (infrastructure-as-code, an application that manages some rules at runtime, and the operator by hand), and re-applying one would silently overwrite another.

Decision. Partition the configuration into zones with a declared owner: code-managed (safe to re-apply), application-managed (runtime state owned by an application; code must never touch it) and manual (operator only, with an emergency-access path). The documentation states the owner of every zone, so "may I apply this?" is a lookup, not a judgment call. The health probes for the application-managed zone were later moved onto independent routing after they turned out to share fate with what they measured (see the health-probe case in Incidents).

Where documentation lives

Decision. Build on the internal application tier behind SSO, and treat the git remote as the emergency-access copy when the home site is down.

Read the full record

Context. Documentation had lived on a standalone host outside the application tier, coupling read access to that host's uptime and to manual publishing. A generated site from the infrastructure repository forced a placement choice.

Option Verdict Why
Keep the static site on the standalone host rejected internal documentation outside the application tier, and no live render from the repository
Build on the internal application tier behind SSO; treat the git remote as the emergency-access copy when the home site is down chosen edits flow to the site on a timer, and an outage falls back to reading markdown

Trade-off accepted. Internal-only by default; disaster-recovery runbooks had to move into tracked paths so they appear in both the site and the fallback. Later. A public mirror was first attempted as one site with masking layered on top. That is a weaker control than exclusion: masking can only hide what it recognizes. The replacement builds two editions from one repository: an internal one, and a public one assembled only from pages that are opted in twice and scanned before they may replace the last good build (see Documentation that stays true).