Architecture review

Updated

July 30, 2026

Architecture review

Goal: Map earlier parts of this book onto your actual repository, produce ARCHITECTURE.md, and a prioritized gap list that drives Capstone—before writing more features ad hoc. Assume Capstone hosts pin NixOS 26.05.

Tip

Capstone is implementation and proof, not discovery. Teams that skip architecture review thrash: secrets half-done, tests theater, deploy only from a laptop. This chapter freezes an honest map of what exists vs Capstone A requirements.

Why this chapter exists

You have skills across concepts through ops. Capstone fails when those skills never land in one coherent flake. Architecture review is the integration gate before code thrash: map, gaps, sequence—then implement.

Theory 1 — Capstone A bar (recall)

Required:

  1. ≥1 NixOS host role understood end-to-end
  2. Home Manager or minimal service-user story
  3. Secrets: sops-nix or agenix
  4. Reverse-proxy / edge pattern
  5. Deploy path: deploy-rs and/or Colmena
  6. ≥1 nixosTest or flake check catching real regressions
  7. CI builds and preferably pushes a cache

Disaster recovery and rollback chapters add wipe/rebuild + rollback proof. Gaps from this chapter should make Capstone sequencing trivial.

Item Your status (fill now)
Host role solid / partial / missing
HM or service user
Secrets
Edge/proxy
Deploy tool
Tests
CI + cache

Theory 2 — Coverage matrix (topic parts)

Part Theme Evidence in repo (examples)
Concepts Foundations, flake shell devShells, language notes
NixOS host First host, users, net, systemd nixosConfigurations.*, host modules
Home & layout Layout, HM, checks home-manager, flake structure
Services & security Secrets, harden, proxy, data sops, firewall, nginx/caddy
Packaging Overlays, caches custom packages, cachix config
Ops & fleet Disko, deploy, images, tests, CI deploy configs, workflows, tests
Internals Evaluator, upgrades notes artifacts; not all need code

Mark each: solid / partial / missing / N/A. Partial without a demo command is missing in disguise.

Theory 3 — Architecture views (write these)

A. Context

Who uses the system? Laptop only? Lab server? Family services? Threat model one paragraph.

B. Containers of code

flake.nix
hosts/
modules/
homes/
secrets/
tests/
deploy/
.github/ or .forgejo/
docs/

C. Runtime view

[client] → [proxy:443] → [app:8080]
                ↓
             [sops secrets]
                ↓
             [deploy-rs/colmena from CI or admin]

D. Trust view

  • Who can decrypt secrets?
  • Who is trusted-users?
  • Which caches are trusted?
  • Where do age master keys live offline?

E. Failure view

  • Boot rollback
  • Deploy failure
  • Secret loss (DR needs offline keys)
  • Cache outage (can you still build?)

F. Data view

  • What is stateful?
  • Where are backups?
  • Impermanence list if any?

Theory 4 — Prioritization

Score gaps:

Priority Definition
P0 Capstone A impossible without it
P1 Required for DR proof quality
P2 Hardening / UX polish
P3 Nice / Capstone B

Sequence Capstone as:

Capstone chapter Suggested focus
Scope and plan P0 host + module skeleton gaps
Implement Secrets + proxy E2E
Harden and document Deploy + CI + cache + docs
Prove rebuild Tests + freeze
Optional multi-node Capstone B bar only if A solid
Disaster recovery Wipe + rebuild timed
Rollback and tests Rollback drill + suite green
Retrospective Honest close-out

Adjust if your matrix differs—write the plan. A plan you do not write will be renegotiated under panic every session.

Theory 5 — Non-goals for Capstone A

Explicitly list what you will not do (protects freeze):

  • Multi-region mesh
  • Full k3s
  • Every self-hosted app
  • Capstone B fleet (unless ahead)
  • Experimental CA store
  • Perfect HA for lab toys

Non-goals are features, not apologies. Scope control is expertise.

Theory 6 — Evidence standards

Claim Acceptable evidence
“We have sops” Decrypt path works on host; secrets.nix in git
“We have CI” Green URL + workflow file
“We have tests” Check that fails when you break a module
“We deploy” Log of remote activation this month
“Architecture exists” ARCHITECTURE.md with diagrams

Screenshots of dashboards without repo paths do not count for Capstone A.

Theory 7 — Dossier structure (feeds Capstone)

Recommended docs layout:

docs/
  ARCHITECTURE.md
  GAPS.md
  CAPSTONE-A.md
  RUNBOOK.md          # deploy/rollback
  TRUST.md            # keys, caches, trusted-users
  playbooks/          # from troubleshooting
  UPGRADE-26.11.md    # from upgrade planning

Capstone chapters will tick CAPSTONE-A.md and deepen RUNBOOK/DR.

Lab 0 — Workspace

mkdir -p ~/lab/nixos/internals/architecture
cd ~/lab/nixos/internals/architecture

Work against the real Capstone flake path.

Lab 1 — Automated inventory

cd /path/to/flake
find . -name '*.nix' | head -200 | tee ~/lab/nixos/internals/architecture/nix-files.txt
nix flake show 2>&1 | tee ~/lab/nixos/internals/architecture/flake-show.txt
rg -n "sops|agenix|deploy-rs|colmena|home-manager|nixosTest|cachix" -g '*.nix' \
  | tee ~/lab/nixos/internals/architecture/feature-hits.txt
ls -la .github/workflows 2>/dev/null || ls -la .forgejo/workflows 2>/dev/null || echo "no CI yet"

Skim flake-show for dead attrs and surprise outputs.

Lab 2 — Coverage matrix

Fill COVERAGE.md:

Part Status Paths Demo command Notes
Concepts
…
Capstone A items 1–7 each row

Be brutal. “I watched a video about sops” ≠ solid.

Lab 3 — ARCHITECTURE.md (required)

Minimum sections:

  1. Purpose & scope
  2. Host roles
  3. Module map
  4. Secrets model
  5. Edge/proxy
  6. Deploy & CI
  7. Test strategy
  8. Trust & keys
  9. Backup/DR pointers
  10. Gap list summary (link)
  11. Non-goals
  12. Pin / release (26.05) policy

Diagrams: ASCII is enough.

Acceptance: A stranger can find rebuild, secrets, and deploy paths in under five minutes of reading.

Lab 4 — Prioritized backlog

GAPS.md:

ID Gap Pri Capstone chapter Acceptance test
G01 No CI cache push P0 Harden/document workflow uploads
…

Every P0/P1 needs an acceptance test you could demo in under five minutes.

Lab 5 — Checklist freeze seed

Create CAPSTONE-A.md checklist (boxes empty/partial/done) that Capstone will tick. Include wipe/rebuild and rollback rows even though execution is later.

# Capstone A checklist

## Core
- [ ] Host role rebuilds from flake
- [ ] HM or service users
- [ ] Secrets E2E
- [ ] Reverse proxy edge
- [ ] Deploy path
- [ ] nixosTest/check
- [ ] CI (+ cache preferred)

## Proof
- [ ] Wipe + rebuild timed
- [ ] Rollback drill + suite green

## Docs
- [ ] ARCHITECTURE.md current
- [ ] RUNBOOK.md deploy/rollback

Lab 6 — Risk register (short)

Three risks that could sink Capstone A:

Risk Likelihood Impact Mitigation
Only age key on lab disk Offline copy now
No console on remote Enable before firewall games
Tests don’t fail on breaks Capstone tests priority

Lab 7 — Sequence plan

Write SEQUENCE.md: ordered list of Capstone sessions with intended gap IDs closed. Keep it one page.

Common gotchas

Mistake Fix
Optimistic “partial = done” Require demo command proof
Skipping docs because “I know it” Capstone is proof for future you
40 P0s Reclassify; cut scope
Planning Capstone B now Park in non-goals
No acceptance tests on gaps Unverifiable work
Architecture file never opened again Link it from CAPSTONE-A.md

Checkpoint

  • Inventory artifacts (flake-show, feature hits)
  • COVERAGE.md part matrix
  • ARCHITECTURE.md complete
  • GAPS.md prioritized with Capstone mapping
  • CAPSTONE-A.md checklist seeded
  • Risk register + sequence
  • Three personal gotchas

Commit

git add .
git commit -m "lab(nixos): architecture review and capstone gap plan"

Write three personal gotchas before continuing.

Next

→ Capstone and recovery — implement Capstone A and prove rebuildability.