improve-codebase-architecture

Iteration loop: explore for friction, present deepening candidates, grill the chosen one, update domain artifacts inline. Vocabulary is load-bearing — see references/LANGUAGE.md.

Vocabulary [LOAD-BEARING]

Use these terms exactly. Do not substitute "component," "service," "API," or "boundary." Full definitions in references/LANGUAGE.md.

• Module — anything with an interface and an implementation (function, class, package, slice). Scale-agnostic.
• Interface — every fact a caller must know: types, invariants, ordering, error modes, config, performance shape. Not just signature.
• Depth — leverage at the interface. Deep = much behaviour behind a small interface. Shallow = interface as complex as implementation.
• Seam (Feathers) — where an interface lives; a place behaviour can be altered without editing in place. Use this, not "boundary."
• Adapter — a concrete thing satisfying an interface at a seam. Role, not substance.
• Leverage — capability callers gain per unit of interface learned.
• Locality — concentration of change, bug, and knowledge at one site for maintainers.

Principles

• Deletion test: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
• Interface = test surface. Tests cross the same seam callers cross. Wanting to test past the interface = wrong shape.
• One adapter = hypothetical seam. Two adapters = real seam. No port without two real implementations (production + test).