NestJS — Enterprise Node.js

Application Architecture Patterns

17 min Lesson 19 of 30

Application Architecture Patterns

NestJS gives you building blocks; architecture is how you arrange them as the app grows. A small project is fine with the default structure, but a large one benefits from clear layers and boundaries. This lesson surveys the patterns that keep big NestJS codebases maintainable.

The default: layered architecture

The structure NestJS encourages out of the box is a layered (N-tier) design, where each layer has one responsibility and depends only on the layer below:

Controller   ->  handles HTTP, validates input, returns responses
Service      ->  business logic and rules
Repository   ->  data access (database queries)
Entity/Model ->  the shape of your data

A request flows down the layers and the response flows back up. The golden rule: a controller never touches the database directly, and a repository never contains business rules.

Layering is about dependency direction. Higher layers depend on lower ones, never the reverse. This keeps business logic independent of how data is delivered (HTTP today, GraphQL tomorrow) or stored.

Modular (feature-based) organisation

Within those layers, organise by feature, not by type. Each feature module is a self-contained slice:

src/
  users/
    users.controller.ts
    users.service.ts
    users.repository.ts
    dto/
    entities/
    users.module.ts
  orders/
    ... same structure
  shared/        # cross-feature utilities

This makes features easy to find, easy to test in isolation, and easy to extract into a microservice later if needed.

Clean / hexagonal architecture

For complex domains, teams push further with clean architecture: the business domain sits at the centre and knows nothing about frameworks or databases. Outer layers (controllers, repositories) depend inward on abstractions, never the other way around:

Domain — entities and business rules, pure and framework-free.
Application — use cases that orchestrate the domain.
Infrastructure — database, HTTP, external services (the replaceable details).

NestJS's dependency injection makes this natural: a service depends on an interface (a token), and you bind the concrete database implementation via a custom provider — so the domain never imports the ORM.

Match the pattern to the problem. Clean architecture pays off for large, long-lived, business-heavy systems. For a small CRUD API it is overkill — the default layered + modular structure is the right amount of architecture.

Practical guidelines

Keep controllers thin: validate, delegate, return.
Put business logic in services; put data access behind a repository.
Organise by feature module; export only what other modules need.
Depend on abstractions (tokens/interfaces) for things you may swap.
Do not over-engineer — add layers when complexity demands them, not before.

Premature architecture is as harmful as none. Wrapping a three-endpoint API in five abstraction layers slows everyone down. Start simple; introduce structure when the pain of not having it appears.

Summary

NestJS defaults to a layered architecture (controller → service → repository) organised into feature modules. As complexity grows, clean/hexagonal architecture keeps the business domain independent of frameworks and databases, which NestJS's DI supports naturally through interface tokens and custom providers. Choose the lightest structure that fits the problem. This completes Phase 4 — your apps are now well-configured and well-structured. Next: the data layer.