# Design Notes

> Architecture decisions, trade-offs, and implementation boundaries behind Barn.

---

LLMS index: [llms.txt](/llms.txt)

---

Barn's source repository once carried the redesign brief, implementation
ADRs, and native evidence beside the code. That material was useful while the
product was changing quickly, but many early decisions were later superseded.
This section keeps the durable reasoning, rewritten against the current source
instead of republishing stale plans.

Start with the product model, then follow the boundaries outward:

1. [Why Barn has no projects](one-deployment-no-projects/) — one Inventory,
   one owner-scoped deployment, and no second source of truth.
2. [Why every node has two NICs](fixed-ip-two-nics/) — fixed identity for the
   lab, separate from management egress.
3. [Declarative does not mean destructive](convergence-without-surprise/) —
   per-node drift with explicit recreate and removal.
4. [A PID is not a virtual machine](identity-before-pid/) — QMP identity,
   process evidence, journals, and bounded recovery.
5. [`repo.yaml` is intent; `catalog.json` is evidence](repo-yaml-catalog-json/)
   — a static image repository whose generated metadata is checked against the
   actual qcow2 bytes.

Use the [documentation](/docs/) for current behavior and the
[status page](/docs/about/status/) for dated verification. These design records
explain why those contracts exist; they do not turn a design, build, or local
test into release evidence.

These articles retain their original publication dates and were last reviewed
against source on **2026-09-26**, with names updated for the Barn 0.9.0 candidate
on **2026-09-29**. Changes specific to an unreleased candidate
are marked separately; historical verification keeps its original date and scope.

---

Section pages:

- [Why Barn Has No Projects](/blog/design/one-deployment-no-projects/): Why Barn replaced per-directory project state with one owner-scoped deployment driven by one Pigsty Inventory.
- [Why Every Barn Node Has Two NICs](/blog/design/fixed-ip-two-nics/): Why Barn separates management egress from the fixed-address network used by the host, peers, Ansible, and Pigsty.
- [Declarative Does Not Mean Destructive](/blog/design/convergence-without-surprise/): How Barn uses per-node hashes and explicit operations so missing configuration can never authorize deletion.
- [A PID Is Not a Virtual Machine](/blog/design/identity-before-pid/): Why Barn combines QMP identity, process evidence, typed invocations, and journals before it signals or deletes anything.
- [repo.yaml Is Intent; catalog.json Is Evidence](/blog/design/repo-yaml-catalog-json/): Why Barn separates human-authored image policy from generated metadata that must match the actual qcow2 artifacts.