Day 82 — Architecture review

Updated

July 30, 2026

Day 82 — Architecture review

Stage VII · ~4h
Goal: Map Stages I–VI (and early VII) onto your actual repository, produce ARCHITECTURE.md, and a prioritized gap list that drives Capstone Days 83–87—before writing more features ad hoc. Assume Capstone hosts pin NixOS 26.05.

Tip

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

Why this day exists

You have ~80 days of skills. 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

Days 88–89 add wipe/rebuild + rollback proof. Day 82 gaps should make 83–87 trivial to sequence.

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

Theory 2 — Stage coverage matrix

Stage Theme Evidence in repo (examples)
I Foundations, flake shell devShells, language notes
II First host, users, net, systemd nixosConfigurations.*, host modules
III Layout, HM, checks home-manager, flake structure
IV Secrets, harden, proxy, data sops, firewall, nginx/caddy
V Packaging, overlays, caches custom packages, cachix config
VI Disko, deploy, images, tests, CI deploy configs, workflows, tests
VII Internals, upgrades day71–81 notes; 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 (Day 88 needs offline keys)
  • Cache outage (can you still build?)

F. Data view

  • What is stateful?
  • Where are backups (Day 69)?
  • Impermanence list if any (Day 58)?

Theory 4 — Prioritization

Score gaps:

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

Sequence Days 83–87 as:

Day Suggested focus
83 P0 host + module skeleton gaps
84 Secrets + proxy E2E
85 Deploy + CI + cache
86 Tests + runbooks + diagrams
87 Freeze, bugfix, checklist

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

Theory 5 — Non-goals for Capstone A

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

  • Multi-region mesh
  • Full k3s
  • Every self-hosted app
  • Capstone B fleet (unless ahead)
  • Experimental CA store (Day 75)
  • 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.

Lab 0 — Workspace

mkdir -p ~/lab/90daysofx/02-nixos/day82
cd ~/lab/90daysofx/02-nixos/day82

Work against the real Capstone flake path.

Lab 1 — Automated inventory

cd /path/to/flake
find . -name '*.nix' | head -200 | tee ~/lab/90daysofx/02-nixos/day82/nix-files.txt
nix flake show 2>&1 | tee ~/lab/90daysofx/02-nixos/day82/flake-show.txt
rg -n "sops|agenix|deploy-rs|colmena|home-manager|nixosTest|cachix" -g '*.nix' \
  | tee ~/lab/90daysofx/02-nixos/day82/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 — Stage matrix

Fill COVERAGE.md:

Stage Status Paths Demo command Notes
I
…
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.

Lab 4 — Prioritized backlog

GAPS.md:

ID Gap Pri Capstone day Acceptance test
G01 No CI cache push P0 85 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 Days 83–89 will tick. Include wipe/rebuild and rollback rows even though execution is later.

# Capstone A checklist

## Core
- [ ] Host role …
## Days
- [ ] 83 …
- [ ] 88 wipe/rebuild
- [ ] 89 rollback + full tests

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 Day 86 priority

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 stage matrix
  • ARCHITECTURE.md complete
  • GAPS.md prioritized with day mapping
  • CAPSTONE-A.md checklist seeded
  • Three personal gotchas

Commit

git add .
git commit -m "day82: architecture review and capstone gap plan"

Write three personal gotchas before continuing.

Tomorrow

Day 83 — Capstone 1/5: implement highest P0 gaps; keep the live checklist honest.