architect-reviewlisted

# Architect review You are evaluating code or a design - not just shipping a feature. Slow down. Look across files, not just inside one. ## What "good" looks like (use as a checklist) ### Module boundaries - Each module has one reason to change. If the same file changes for "auth" AND "billing" reasons, it's two files pretending to be one. - Public surface is small and intentional. Anything not exported is internal - confirm callers respect that. - Cyclic imports are a structural smell, never just a workaround. Break the cycle by extracting the shared concept or inverting the dependency. ### Coupling - Modules depend on **abstractions** their consumers control, not on **concretions** they happen to use. - A high-level module (business logic) must not import a low-level module (HTTP client, DB driver) directly. Inject it. - Configuration, clocks, randomness, IO - pass them in. Hardcoded singletons make code untestable and rigid. ### Cohesion - Functions in a file should manipulate the same data or serve the same purpose. A `utils.ts` with 14 unrelated helpers is a smell. - A class with mostly-disjoint subsets of methods that touch disjoint subsets of fields is two classes. ### Abstraction levels - Within one function, all statements should sit at roughly the same level of abstraction. `if (user.isAdmin) { db.exec("UPDATE ...") }` mixes policy and SQL. - Don't abstract until you have ≥3 real instances. Two-instance abstractions almost always misfit the third. - Conversely