improve-codebase-architecturelisted

# Improve Codebase Architecture Explore a codebase like an AI would, surface architectural friction, discover opportunities for improving testability, and propose module-deepening refactors as GitHub issue RFCs. A **deep module** (John Ousterhout, "A Philosophy of Software Design") has a small interface hiding a large implementation. Deep modules are more testable, more AI-navigable, and let you test at the seam instead of inside. ## Working vocabulary Use these terms exactly when describing architectural opportunities, in conversation with the user, in candidate write-ups, and in the resulting RFC issue. Do not drift into "component," "service," "API," or "boundary" — they read as synonyms but each one hides a different design decision and the slippage compounds across recommendations. - **Module** — a unit of code that callers interact with through a stable interface. Files, classes, packages, or directories can all be modules; the test is whether something on the outside depends on something on the inside. - **Interface** — the surface a module presents to callers: types, methods, parameters, return shapes, errors. Not the implementation. - **Implementation** — the code behind the interface that callers do not see and should not depend on. - **Depth** — the ratio of implementation hidden to interface exposed. Deep = a lot hidden behind a narrow surface; shallow = the interface is nearly as complex as the body. - **Seam** — a place in the codebase where one module ends