How to structure a project folder so it explains itself

How you organize your project folders directly affects how fast a developer can find and change code. Two main patterns exist: layer-based and feature-based. Both are legitimate — picking the wrong one for your project size is the mistake.

Layer-based groups by technical role:

src/
  controllers/
  models/
  services/
  utils/

Works well for small projects. Breaks down when projects grow because a single feature change touches five folders.

Feature-based groups by domain concept:

src/
  users/
    user.model.js
    user.service.js
    user.controller.js
    user.test.js
  orders/
    order.model.js
    order.service.js

Scales well because everything about a feature lives together. A change to orders touches only the orders folder. This is the pattern used by most modern applications at scale.

Regardless of pattern, the project root should be self-explanatory. A developer seeing your project for the first time should immediately understand what it is by reading the folder names — no spelunking required.

Keep configuration files (.eslintrc, tsconfig.json, Dockerfile) at the root. Keep test files next to the source they test, not in a parallel tests/ directory — colocating tests makes it obvious when source files have no tests.