codebase-design

Topics in the source

• Codebase Design
• Glossary
• Deep vs shallow
• Principles
• Designing for testability
• Agent legibility
• Relationships
• Rejected framings

Design deep modules: substantial behaviour behind a small interface at a clean seam, testable through that interface. Use this vocabulary when it clarifies a design decision. The aim is leverage for callers, locality for maintainers, and testability. Use these terms consistently where their distinctions matter. Module: anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. Avoid: unit, component, service. Interface: everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. Avoid: API, signature (too narrow because they refer only to the type-level surface). Implementation: what is inside a module, its body of code. Distinct from Adapter: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). When the seam is the topic, use "adapter". Otherwise, use "implementation". Depth: leverage at the interface. The amount of behaviour a caller (or test) can exercise per unit of interface they have t

This is an excerpt. Refer to the complete source and its current requirements.