system-architecturelisted

# System Architecture Design the shape of the solution before anyone builds it: what the pieces are, how they fit, and where the seams go. Aim for **deep modules** — a lot of behaviour behind a small interface — not a sprawl of shallow ones. ## When to use - You have approved requirements and the work is non-trivial — a new subsystem, several components, real integration. - **Skip** for a small feature; its structure lives in `writing-plans`' interface map, not a separate design. ## Procedure 1. **Components and boundaries.** Name each module by what it *does* and what it deliberately *doesn't*. A module earns its place if removing it would spread its complexity across the callers; if complexity merely relocates, it's shallow — merge it. 2. **Data flow.** Trace the request/response and event paths end to end. Each should be followable from entry to effect. 3. **External services.** Map every third party (payments, mail, realtime, storage). For each, state the testability strategy: how you trace the data path through it, and how you behave — and test — when it's unavailable. 4. **Seams.** Put boundaries where you'd swap an implementation, and inject across them. Don't add a port for a *hypothetical* seam — two real adapters justify one; one doesn't. 5. **Decide the load-bearing choices deliberately.** For each significant, hard-to-reverse structural decision, weigh the options on four axes — what it assumes, where it breaks down, what would rule it out, what evidence supp