# Design Notes

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

---

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

---

This section explains the architecture and implementation choices in the
Barn 0.9.0 candidate.

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.

---

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.