Architect Skill

Glossary

Precise vocabulary for every architectural decision. Use these terms exactly — consistency is the point.

• Module — anything with an interface and an implementation (function, class, package, layer). Router, Service, Entity, and Repository are all modules.
• Interface — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature.
• Seam — where a module's interface lives; a place behaviour can be altered without editing in place. The functional core / effectful edge boundary is the primary seam.
• Depth — leverage at the interface. A module is deep when a lot of behaviour sits behind a small interface. A module is shallow when the interface is nearly as complex as the implementation.
• Adapter — a concrete thing satisfying an interface at a seam. A Postgres repository is an adapter; an in-memory fake for testing is another adapter at the same seam.
• Leverage — what callers get from depth: more capability per unit of interface they learn.
• Locality — what maintainers get from depth: change, bugs, and knowledge concentrate in one place.

Key principles (apply to every decision):

• The 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.
• The interface is the test surface. Callers and tests cross the same seam. If you want to test past the interface, the module is probably the wrong shape.
• One adapter = hypothetical seam. Two adapters = real seam. Don't introduce a seam unless something actually varies across it.