How I extended NestJS's architecture for projects that outgrow the basics

Matteo Tomičić — Thu, 07 May 2026 20:20:51 +0000

NestJS ships with a great starting point. The module/controller/service pattern is clean, approachable, and gets you productive fast. For most projects, it's exactly what you need.

But as a project grows - more features, more teammates, more complexity - that foundation benefits from a bit more structure. Not a full rewrite, not a completely different paradigm. Just a few extra layers with clearly defined responsibilities.

This is what I came up with, and why.

The challenge with scaling the default structure

The built-in structure doesn't tell you where shared technical concerns go, how to organize services as they multiply, or where external integrations like email or file storage belong. That's not a flaw - the framework intentionally leaves those decisions to you.

Without deliberate decisions, though, you'll eventually run into familiar growing pains: services that accumulate too many responsibilities, shared utilities scattered without a clear home, and new developers spending their first days just figuring out where things live.

Full Clean Architecture solves these problems - but it also introduces a significant amount of abstraction that can feel heavy for a small or mid-sized project. Interfaces for things that will never change. Layers for layers' sake.

I wanted something in between: structured enough to scale, simple enough to onboard quickly.

Four layers, clear boundaries

I extended the default structure with four top-level groups, each with a clearly defined role:

src/
  common/         ← global technical infrastructure
  core/           ← stable infrastructure services
  integrations/   ← wrappers around external services
  modules/        ← business logic, by domain

The value isn't in the folders themselves - it's in the rules each one follows.

common/ - technical, global, domain-free

Everything the framework needs to function, with zero knowledge of your business domain: global exception filter, response formatting interceptors, guards, custom decorators, global middleware, shared enums, TypeScript extensions for the request object.

The rule: if something in common/ needs to know what "business" means in your application - it doesn't belong in common/.

This is also where the global ValidationPipe lives, configured with whitelist: true. That single option automatically strips any properties not declared in a DTO before they reach your business logic. Security as a default, not something you bolt on later.

core/ - set it up, then forget it

core/ holds the application's internal technical infrastructure - things with no business logic, configured once and rarely touched:

core/
  config/
    env/        ← env validation and typed access to variables
  database/     ← connection, setup
  queue/        ← BullMQ configuration and provider

The key distinction from integrations/: everything in core/ is internal to the application. No API calls to the outside world, no third-party dependencies - just the setup of what the application runs itself.

The env setup deserves a special mention. Rather than accessing process.env.SOMETHING throughout the codebase and discovering at runtime that a variable is missing, env gets validated at startup. Wrong type or missing value - the app won't start. A small investment that saves hours of production debugging.

integrations/ - one place for every external service

This is the layer that's most often missing in NestJS projects, and its absence is felt as soon as the project scales. Every external service the application talks to gets its own module here:

integrations/
  mailer/     ← email sending (SendGrid, SMTP, ...)
  storage/    ← file uploads (S3, local disk, ...)
  stripe/     ← payment processing
  sms/        ← SMS notifications (Bind, ...)

mailer/ isn't just "send an email" - it's a wrapper that owns the SMTP configuration, templates, and retry logic. That logic doesn't belong inside the feature module that happens to use it, but it also doesn't belong in core/ which should stay independent of external services.

The practical payoff: when you swap SendGrid for AWS SES, you change one directory. Every feature module that uses mailer/ is completely unaffected.

modules/ - where the actual work happens

Every feature module follows the same internal structure, whether it's orders, users, products, or anything else:

modules/[feature]/
  dtos/                  ← input DTOs with validation
  repositories/          ← direct database access
  services/
    internal/            ← shared services within the module
    use-cases/           ← one service = one operation
  types/                 ← TypeScript types specific to this module
  [feature].controller.ts
  [feature].module.ts

dtos/ - validation at the entry point

DTOs are classes that define what the controller is allowed to receive, with validation rules declared via class-validator decorators. One DTO per operation:

dtos/
  create-order.dto.ts
  update-order.dto.ts
  cancel-order.dto.ts

Combined with whitelist: true on the global ValidationPipe, anything not explicitly declared in a DTO gets automatically rejected - without writing that check in every controller.

use-cases/ - one service, one operation

This is the most impactful decision in the whole architecture. Each file represents exactly one operation:

use-cases/
  create-order.service.ts
  cancel-order.service.ts
  confirm-order.service.ts
  get-order-summary.service.ts

When a product manager reports a bug in the cancel order flow - you know exactly which file to open. When someone new joins the project and asks where the order creation logic lives - create-order.service.ts answers the question before they finish asking.

But readability isn't the only win here. This structure directly improves testability. Writing a unit test for a service with a single, clear responsibility is straightforward. Writing a unit test for a service with fifteen methods and a tangle of dependencies is the kind of work that always gets pushed to "later" - and later never comes.

With NestJS's DI system, each use-case service can be tested in isolation, mocking only the dependencies it actually needs.

internal/ vs use-cases/ - a distinction worth making

use-cases/ are the services a controller calls directly. One entry point, one responsibility.

internal/ are services used by other services within the module, but never directly by the controller. Example: a service that calculates order pricing with discounts - logic shared across multiple use cases, but not itself an operation the controller triggers. Pulling it into internal/ avoids duplication and gives you one focused place to test that logic.

Deliberate trade-offs

Repositories live inside their module, not in a shared Infrastructure layer. The reason is pragmatic: the orders repository is only ever used by the orders module. Abstracting something that isn't shared adds files and indirection without benefit. If two modules eventually need the same repository, that's the moment to refactor - not a reason to architect for it on day one.

This structure also deliberately skips repository interfaces and ORM abstraction layers. For a smaller project, that flexibility is largely theoretical. The code required to support it is real, and it carries a real maintenance cost.

The test that matters

Architecture should solve the problems a project has today, not imaginary problems it might face in two years. For a small team, this structure delivers predictability, built-in validation safety, and testability - without the overhead of a full Clean Architecture setup.

The question I ask about any architectural decision isn't "is this theoretically correct?" It's "will a new developer understand where things go and where to find them within 30 minutes?"

If the answer is yes - the architecture is doing its job.

How do you approach NestJS architecture on smaller projects? Do you separate external services into a dedicated integrations/ layer, or pull them directly into modules? I'd love to hear what's worked - and what hasn't - from your experience in production.

DEV Community: Matteo Tomičić