/improve-codebase-architecture

Explore a codebase like an AI would, surface architectural friction, and propose module-deepening refactors as GitHub issue RFCs.

Structured execution spec: protocol.yon. Read it for the canonical rules and step sequence; this file is explanation. The two must stay in sync — if you edit one, update the other and refresh the @STAMP date.

A deep module has a small interface hiding a large implementation. Deep modules are more testable, more AI-navigable, and let you test at the boundary instead of inside. (John Ousterhout, A Philosophy of Software Design)

The deepening test: would merging these modules produce a smaller combined interface than they have separately? If no, it's not a deepening opportunity — it's just reorganization.

Reference — Dependency Categories

Classify each candidate's dependencies; the category determines the entire testing strategy.

1. In-process — pure computation, in-memory state, no I/O. Always deepenable; merge and test directly.
2. Local-substitutable — dependencies with local test stand-ins (PGLite for Postgres, memfs for filesystem). Deepenable if the stand-in exists; test the merged module with the stand-in running in the suite.
3. Remote but owned (Ports & Adapters) — your own services across a network boundary. Define a port at the boundary; the deep module owns the logic, transport is injected. Tests use an in-memory adapter; production uses the real one.
4. True external (Mock) — third-party services you don't control (Stripe, Twilio). Mock at the boundary; the deepened module takes the external dependency as an injected port, tests provide a mock.