Codebase Design

Codebase Design

Design deep modules: a lot of behavior behind a small interface, placed at a clean seam, testable through that interface.

Glossary

Use these terms exactly - consistent language is the point.

• Module - anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice.
• Interface - everything a caller must know to use the module correctly: type signature, invariants, ordering constraints, error modes, configuration, and performance characteristics.
• Implementation - what is inside a module, its body of code.
• Depth - leverage at the interface: the amount of behavior a caller can exercise per unit of interface they have to learn.
• Seam (Michael Feathers) - a place where you can alter behavior without editing in that place.

Principles

• Deep over shallow: prefer a small interface that hides lots of behavior
• Test through the interface: if the seam is clean, the test is simple
• Caller leverage: every line of interface should unlock multiple lines of behavior

Common Pitfalls

• Inconsistent terminology: Do not substitute 'component', 'service', 'API', or 'boundary' for the defined terms. Consistent language is the whole point.
• Depth over everything: Depth is a goal, but not the only one. Performance requirements, operational constraints, and team familiarity also matter.
• Seams placed at the wrong level: A seam should match a natural boundary in the domain, not an architectural fashion. Forcing seams where they do not belong creates accidental complexity.

Code Examples

// Deep module example: small interface, complex implementation

interface PaymentProcessor {
  charge(amount: Money, source: PaymentSource): Result<Payment>;
  refund(paymentId: string): Result<Payment>;
}

// Implementation handles: retries, idempotency, webhook verification,
// currency conversion, fee calculation, receipt email,
// fraud detection, dispute handling, logging
// But caller only sees charge() and refund()
class StripePaymentProcessor implements PaymentProcessor {
  // ... complex internals hidden behind a simple interface
}

Verification Checklist

• Module terminology used consistently throughout
• Interface signatures are clear and minimal
• Depth evaluated: behavior per unit of interface
• Seam boundaries identified and justified
• Design principles documented