Package by Feature vs by Layer

## The question every codebase has to answer Every non-trivial codebase eventually has to answer a basic question: when I create a new class, which folder does it go in? There are two dominant answers, and they cut the same set of classes along different axes. ## Package-by-layer Package-by-layer (sometimes called 'horizontal slicing') groups classes by their **technical role** in the application's architecture. - A typical Spring or Express-style project ends up with top-level packages like `controllers`, `services`, `repositories`, and `dtos`. - Every controller in the system — `OrderController`, `UserController`, `PaymentController` — lives in the same `controllers` package, regardless of which business feature it belongs to. - It mirrors the classic **three-tier** mental model (presentation, business logic, data access) that most backend frameworks and tutorials teach by default, and it is the layout code generators and boilerplate templates produce out of the box. ## Package-by-feature Package-by-feature (also called 'vertical slicing' or organizing by 'module') instead groups classes by the **business capability** they implement. - An `orders` package contains `OrderController`, `OrderService`, `OrderRepository`, and `OrderDto` — everything needed to understand or modify ordering, regardless of which architectural layer each class belongs to. - A sibling `users` package holds the equivalent set for user management. - The package boundary tracks 'what this code is for', not 'what kind of class this is'. ## What the layer layout gets right The problem package-by-layer solves, historically, is **discoverability by role**: if you know you're debugging a persistence issue, you know to look in `repositories`, full stop. It also happens to be the layout that matches how architecture diagrams are usually drawn (boxes for tiers, arrows for calls), so junior engineers coming from a course or tutorial recognize it instantly. That's a real, if modest, benefit, and it's why almost every 'hello world' web app tutorial ships with this layout. ## The problem it creates The problem it creates is **locality of change**. Real feature work almost never respects layer boundaries: adding a `discountCode` field to orders touches `OrderController`, `OrderService`, `OrderRepository`, and probably `OrderDto` and a validator — four or five files scattered across four or five top-level packages, interleaved alphabetically with completely unrelated classes from every other feature. Robert C. Martin named this problem in his 'Screaming Architecture' essay: when you open the top level of a package-by-layer project, the folder names scream 'Spring MVC application' or 'this uses a repository pattern' rather than screaming 'this is an e-commerce system' — the technical framework is more visible than the business the software actually does. Package-by-feature flips that: the top level reads `orders`, `catalog`, `shipping`, `payments`, which is a table of contents for the business domain, not the tech stack. ## Cohesion and coupling The coupling and cohesion argument is the mechanical reason this matters beyond aesthetics. 1. **Cohesion** is how strongly the things inside one module belong together; **coupling** is how much modules depend on each other. 2. Package-by-layer produces packages with **low cohesion** internally — `services/` bundles `OrderService` next to `UserService` next to `PaymentService`, which have nothing to do with each other except that they're all 'services' — while coupling is smeared across the whole tree, because `OrderController` in one package has to import `OrderService` from another and `OrderRepository` from a third, for every feature, every time. 3. Package-by-feature inverts this: each feature package is **highly cohesive** (everything inside it collaborates to do one job) and, ideally, features are only loosely coupled to each other, often only through explicit shared interfaces or a small `common`/`shared` package. ## The encapsulation the layer layout cannot offer That inversion also unlocks encapsulation that package-by-layer structurally cannot offer in languages with package-scoped visibility (Java, Kotlin's internal-per-module patterns, Go's unexported identifiers). Under package-by-feature, `OrderRepository` can be **package-private** — visible only inside `orders` — so nothing outside the feature can bypass `OrderService` and query the database directly. Under package-by-layer this is nearly impossible, because `OrderRepository` sits in a `repositories` package alongside every other feature's repository, and anything with access to that package can reach in. ## Where most codebases land In practice, most production codebases end up doing package-by-feature at the top level and package-by-layer one level down — `orders/controller`, `orders/service`, `orders/repository` — getting the locality-of-change and encapsulation benefits of feature slicing while still giving each feature package internal structure a newcomer to that one feature can navigate.