structure-codebase

Organize files by capability, feature, or use case so code that changes together lives together, and expose a small explicit public API per module. Avoid global buckets like controllers, services, or utils that scatter one behavior across the tree.

Use a visible hexagon only when the project explicitly adopts ports and adapters and the boundary has meaningful provider-free application policy, purposeful ports, test interactors, and import enforcement. Simple CRUD, scripts, and small packages should stay flat or feature-first.

Declare a role for each package, validate both source imports and package.json dependencies, and protect boundaries with explicit public exports. For deep workspaces, test recursive package discovery at the deepest target path before moving code.

No. Bounded contexts define language and model authority while a hexagon defines a technology test wall, and each can exist without the other. Organize DDD projects by context and domain language without manufacturing adapters or port interfaces.

Frontend structure follows route ownership, product-feature cohesion, UI reuse level, state and data ownership, and client/server runtime boundaries. Do not project backend hexagon, ports, or composition-root vocabulary onto client code unless the frontend explicitly earns that boundary.

Record the decision, map current behavior, add characterization tests, prepare enforcement, decompose god files, invert leaked dependencies, then reparent packages one capability at a time. Never combine mass file moves with behavior changes in one step.