Structuring a Codebase: By Layer, By Feature, or By Domain?

You open a new project and the first thing you do — before writing a single line of logic — is create a folder. Maybe it's called controllers/. Maybe it's called orders/. Either way, that quiet choice is already an architectural decision, and it will quietly shape everything that follows: how fast a new teammate finds their footing, how many files you touch when a single feature changes, and whether six months from now your codebase reads like your business or like your framework.

This post is a practical tour of the three main approaches — by-layer, by-feature, and screaming (by-domain) — with honest trade-offs at each company size. No single answer wins for every situation, but you'll leave with a clear mental model for choosing deliberately instead of by default.

Why folder structure is an architectural decision, not bikeshedding

People dismiss folder structure as "just organization". It's much more than that. The way you group code controls three things that turn out to matter enormously:

• Coupling. When code that changes together lives far apart, every small update turns into a cross-folder expedition. When it lives together, related changes cluster in one place.
• Discoverability. A developer unfamiliar with your codebase will ask, "where is the code for billing?" The answer to that question — one folder, or five scattered folders — determines onboarding time.
• Blast radius. How many files must you open to ship a new feature, or to safely delete an old one? Structure either constrains that blast radius or lets it sprawl unchecked.

Conway's Law — the observation that software systems mirror the communication structures of the teams that build them — applies here too. If your team is organized around business capabilities (a payments squad, an orders squad), a by-feature structure will feel natural and enforce the right boundaries. A by-layer structure will fight you.

By layer: the familiar default

By-layer organization groups files by their technical role. A typical Node or Spring Boot project ends up looking something like this:

src/
├─ controllers/
│  ├─ OrderController.ts
│  ├─ UserController.ts
│  └─ BillingController.ts
├─ services/
│  ├─ OrderService.ts
│  ├─ UserService.ts
│  └─ BillingService.ts
├─ repositories/
│  ├─ OrderRepository.ts
│  ├─ UserRepository.ts
│  └─ BillingRepository.ts
└─ models/
   ├─ Order.ts
   ├─ User.ts
   └─ Invoice.ts

Every web framework tutorial lands here. Rails does it, Spring Boot's starter does it, Express generators do it. That familiarity is its main asset.

Where by-layer shines:

• Small apps with two or three features — the structure is so flat it barely matters.
• Teams where everyone works across all features; the layer is the unit of specialization.
• Prototypes and internal tools where speed of initial setup beats long-term clarity.

Where by-layer hurts:

• A single feature is scattered across folders. Adding a "refund" feature means touching controllers/, services/, repositories/, and models/. That's four folders for what is conceptually one thing.
• Deleting a feature is an archaeology project. How do you know which files in services/ belong to billing versus orders? The folder name doesn't tell you.
• Merge conflicts multiply. Every feature change touches the same layer-level files, causing collisions when two developers work in parallel.

By feature: a change lives in one folder

By-feature organization groups files by the slice of the product they serve. The technical layers (controller, service, model) still exist — they just live inside each feature folder instead of at the top level:

src/
├─ orders/
│  ├─ OrderController.ts
│  ├─ OrderService.ts
│  ├─ OrderRepository.ts
│  └─ Order.ts
├─ billing/
│  ├─ BillingController.ts
│  ├─ BillingService.ts
│  ├─ BillingRepository.ts
│  └─ Invoice.ts
├─ auth/
│  ├─ AuthController.ts
│  ├─ AuthService.ts
│  └─ User.ts
└─ shared/
   ├─ database.ts
   ├─ logger.ts
   └─ Money.ts

Where by-feature shines:

• A change lives in one folder. Adding a refund flow means adding files inside billing/ — no other folder is touched. The blast radius is small and contained.
• Deleting a feature is simple. Remove the folder. If something outside still imports from it, your IDE will tell you immediately.
• Ownership is obvious. The payments team owns billing/; the identity team owns auth/. Monorepo tooling and code review rules can enforce this mechanically.
• Onboarding is faster. A new hire working on orders reads only orders/. They don't need to understand the whole codebase first.

Where by-feature needs care:

• Shared code placement is awkward. The Money type is used by both orders/ and billing/. Does it live in orders/? That feels wrong. It ends up in shared/ — which can itself grow into a second junk drawer if nobody owns it.
• Cross-feature dependencies need discipline. If orders/OrderService.ts imports directly from billing/BillingService.ts, you've created a coupling that the folder structure can't see. Teams use linting rules (eslint-plugin-import/no-restricted-paths) or module-boundary tooling (Nx, NestJS modules) to make these explicit.

Screaming Architecture: what does your top level say?

Uncle Bob (Robert C. Martin) coined the term Screaming Architecture in a famous blog post: "What does the architecture of your application scream? When you look at the top-level directory structure, and the source files in the highest-level package; do they scream: Health Care System, or Accounting System, or Inventory Management System? Or do they scream: Rails, or Spring/Hibernate, or ASP.Net?"

The insight is elegant: if your top-level folders are controllers/, models/, views/, your codebase is screaming MVC framework. The framework is a tool — it shouldn't be the first thing a reader encounters.

Screaming Architecture (also called by-domain) takes by-feature one step further. Not only are features at the top level — the names of those features are drawn directly from the business language (the Ubiquitous Language of Domain-Driven Design), not from technical roles:

// Screams "e-commerce platform"
src/
├─ catalog/          // the domain concept: a product catalog
├─ ordering/         // the domain concept: placing and tracking orders
├─ fulfillment/      // the domain concept: picking, packing, shipping
├─ payments/         // the domain concept: charges, refunds, invoices
└─ identity/         // the domain concept: accounts, auth, permissions

// Compare with the framework-screaming alternative:
src/
├─ controllers/      // screams "MVC"
├─ models/           // screams "ORM"
├─ views/            // screams "templating engine"
└─ services/         // screams "service layer pattern"

Inside each domain folder the internal layout is up to the team — and that's fine. The key promise is that the top level communicates the business, not the infrastructure. A new developer (or your CTO, or a domain expert from the business side) can read the top-level folders and understand what the system does without knowing how it's built.

Side-by-side comparison

Here is an honest appraisal across five practical dimensions:

The pragmatic hybrid most good teams land on

In practice, the best teams don't pick one approach and apply it everywhere with religious consistency. They use a pragmatic hybrid: feature or domain folders at the top, small technical layers inside each one.

This hybrid buys you the best of both worlds:

• The top level screams your business — newcomers know immediately that this is an e-commerce app, not a generic MVC skeleton.
• Each feature is self-contained — a change to the billing flow touches only billing/.
• Technical layers still exist inside each folder, so developers who think in MVC or Clean Architecture layers aren't lost. They just look inside the feature folder.
• A shared/ folder holds truly cross-cutting concerns (a Money value object, a logger, a database connection). The key rule: if something is added to shared/, it should be extracted and owned deliberately — not dumped there as an escape hatch.

At team scale: enforced boundaries and monorepos

As a codebase grows and multiple teams contribute, folder conventions alone aren't enough — a developer can always reach across a boundary with a quick relative import. The next step is making boundaries enforced:

• NestJS modules make inter-module dependencies explicit: you only get access to what another module exports. An import that crosses a module boundary without going through the public API is a compile error.
• Nx boundary rules let you declare which features or libraries are allowed to depend on which others, and then enforce it as a lint error in CI.
• Monorepos take this furthest: each domain (orders, billing, auth) becomes its own package with its own package.json, its own tests, and explicit published exports. Turborepo and Nx are the dominant tools in the JavaScript ecosystem for managing this. The structure looks less like a folder tree and more like a graph of packages — but the underlying idea is identical: group by business capability, make boundaries explicit, enforce them mechanically.

The jump to a monorepo isn't always necessary. Many teams operate happily with a single package and a well-disciplined hybrid structure for years. Reach for monorepo tooling when cross-team coupling becomes a real pain — not preemptively.

Recommendations by company size

The right structure depends on where your organization is today. Here's a direct recommendation for each stage:

Seeing the difference: what lights up when you ship a feature

The most concrete way to feel the difference between by-layer and by-feature is to ask: which boxes light up when I add a new feature?

This diagram is the clearest argument for feature-based grouping. "Blast radius" is not an abstract concept — it's the number of folders and files you open in a single pull request. Reviewers, CI pipelines, and git blame all work better when a feature change is one cohesive chunk, not a smear across every layer.

Now that you've seen how to structure code inside a single service, the natural next question is what to do when one service isn't enough. Read on: Monolith → Microservices.