Codebase Design

Owns: shared codebase-design vocabulary.

Use this reference to reason consistently about module boundaries. It provides language and design exercises; it does not implement, review, schedule, or deliver changes. The calling workflow retains ownership of decisions, artifacts, and side effects.

Vocabulary

• Module: a cohesive unit that owns a useful capability behind a boundary.
• Interface: the surface callers must understand to use a module.
• Implementation: the decisions and machinery hidden behind the interface.
• Depth: the amount of useful complexity hidden by a comparatively small interface.
• Seam: a deliberate boundary where behavior or a dependency can be substituted and observed.
• Adapter: a translation layer between a module's internal model and an external dependency or protocol.
• Leverage: the value delivered by each concept a caller must learn.
• Locality: the degree to which a change can be understood and made within one coherent place.

Design principles