The architecture doc: proof you built a system, not a demo
A portfolio project's code shows you can implement. The architecture doc shows you can engineer — that you made tradeoffs on purpose and know how your system fails. For hiring conversations and for teammates, it's the highest-leverage page you'll write; chapter 24's postmortem template was its incident-shaped sibling.
The eight sections
Run the editor — the checklist is the doc's skeleton, and each section maps to a chapter you've done the work in. Two get special emphasis because their absence is the tell of a demo:
- Failure modes. Name the top three ways the system breaks (upstream schema drift? label delay? traffic spike?), the blast radius of each, and the rollback. Chapter 16's incident lesson and chapter 45's registry gave you the vocabulary; a doc that can't answer "what happens when it's wrong?" hasn't met production yet.
- Evals & slices. Not "accuracy 0.88" but the suite, the floors, the worst slice and what you did about it (chapter 41's triage, summarized). This is the section that distinguishes measured work from vibes at a glance.
Keep it one to two pages, dated, versioned next to the code, and updated when the system changes — a stale architecture doc misleads with authority (the fate this course's own audit exists to prevent).
Diagrams: boxes, arrows, no flattery
One diagram: data sources → pipeline stages → training/registry → serving → monitoring, with arrows for data flow. The mermaid or ASCII sketch that is accurate beats the beautiful one that omits the manual step you run by hand every Tuesday — draw the system you have, including its shame; the shame is the roadmap.
Where AI specifically gets this wrong
- Generated docs that describe the ideal, not the actual. Ask Cursor to document your repo and it narrates the code's aspirations. Verify every claim against what runs — you are the fact-checker of your own doc.
- README-as-architecture-doc. Install instructions are not design rationale. Both, separately.
- Write-once docs. The doc is versioned with the system or it rots into chapter 24's "confidently wrong" artifact.