structure-codebase

Group files by the behavior or use case that changes together, keeping routes, schemas, tests, and persistence colocated per feature. Avoid global buckets like controllers, services, or repositories that scatter one behavior across the tree.

Use a visible hexagon only when the project explicitly adopts ports and adapters with meaningful provider-free application policy, real port conversations, and test interactors at each port. Simple CRUD, scripts, or provider wrappers do not earn the boundary.

Combine package manifests, explicit public exports, project references, and architecture tests that validate both source imports and package.json dependencies. For deep workspaces, derive rules from package roles and test recursive discovery at the deepest target path.

Separate semantic changes from mechanical moves: record the decision, add characterization tests, prepare enforcement, decompose god files, invert leaked dependencies, then reparent packages one capability at a time. Never combine mass moves with behavior changes.

No. Bounded contexts define language and model authority while a hexagon defines a technology test wall; the axes are independent. DDD can use context-first organization with explicit public contracts without manufacturing port interfaces.