In a NestJS hexagonal architecture, use transport DTOs for HTTP or message contracts, application commands and results for use cases, and domain entities or value objects where business identity and rules matter. Keep database representations inside persistence adapters.

You do not need a new class for every function call.

The NestJS Skills documentation covers the broader architecture and object-design guidance. The repository includes the rules and examples behind it.

Version context: this example targets NestJS 11.2.7, TypeScript 5.9.3, class-validator 0.15.1, and class-transformer 0.5.1.

The Nest links use the v11 documentation because the default documentation may describe a newer major version. Follow your project's conventions first, while checking that its validation and deطpendency-injection setup actually works at runtime.

Find the boundary before choosing the type

Hexagonal architecture, also called ports and adapters, separates the business core from the technologies around it. The core should be understandable and testable without starting an HTTP server or connecting to a database.

Inside that core, the domain owns business meaning and rules. An application use case coordinates one goal, such as logging in: load the needed state, ask the domain to apply its rules, and call the required external capabilities. Separating these roles does not require a large class hierarchy.

Ports define the contracts for those interactions. An incoming port exposes an operation such as Login.execute. An outgoing port describes a capability the application needs, such as UserRepository.findByEmail. The contract describes expected results and failures as well as the method signature. You do not need an interface for every helper.

Adapters connect those contracts to technology:

1. An incoming adapter, such as a Nest HTTP controller, receives a request, validates its transport data, and invokes the application operation.

2. The application coordinates domain behavior and calls outgoing ports when it needs stored data or another external capability.

3. An outgoing adapter, such as a SQL repository, implements a port and translates persistence records into the promised result.

4. The incoming adapter maps the application result back to an HTTP response.

Source dependencies point inward: adapters depend on the application's contracts, and the application can depend on the domain. The domain does not import the HTTP controller or SQL adapter. A runtime call can still travel outward to the database through an injected port implementation.

For the User/Auth example below, an HTTP request reaches the login use case, a repository adapter loads the user, the domain checks account state, and the controller returns a mapped result. A test can call that same use case with an in-memory repository. Another adapter can later implement the same port if it preserves the contract's behavior.

This approach helps when an application has substantial business rules or needs to stay maintainable through years of changes. It also helps when several incoming adapters need the same operations or when you may replace an external provider. For example, an order-payment use case can serve both an HTTP checkout and a queue consumer while calling a replaceable payment-provider adapter. A small CRUD service with few rules and one stable data source may not justify the extra abstractions.

Isolated tests and adapter replacement become easier, but you have more contracts, wiring, and mapping to maintain. Add those abstractions where they protect a real boundary.

The hexagon does not mean six layers, six modules, or one mandatory folder layout. A Dto suffix or a folder named domain does not establish the architecture; the imports, data flow, and ownership do.

Give each data shape a clear job

A DTO carries data between parts of a system. It can describe an HTTP request, an API response, a queue message, or the input and result of an application operation. It does not have to be a decorated class.

An entity has identity and continuity across changes. A value object describes a value and its rules, such as money with a currency or a valid date range. A domain model also includes business behavior and policies. Naming a TypeScript interface User does not, by itself, give it those rules.

An application command such as LoginCommand describes a use case's input. It can be a plain type. Calling it an application DTO is also reasonable; ownership and behavior matter more than the suffix.

Two Nest modules can still belong to one domain boundary. A folder split alone does not require a DTO conversion. Across independently owned capabilities, however, importing another module's internal entity can make an unrelated change break your code.

Type, interface, class, or schema?

A TypeScript type or interface works well for an internal contract. It helps the compiler check callers. It disappears from the JavaScript output, so it cannot inspect JSON at runtime.

An ordinary class has a runtime constructor. It can hold behavior or provide a Nest injection token. Its declared field types still do not validate incoming values.

A decorated DTO class supports the familiar ValidationPipe plus class-validator path. A runtime schema is another option: a custom pipe can parse an unknown value and return a typed result. In either approach, the runtime check is the part that establishes trust. JSON.parse(...) as User only tells the compiler what to assume.

Nest's v11 validation guide explains why concrete classes matter for reflected DTO validation. Import a DTO class as a runtime value when Nest needs its metadata. A type-only import cannot provide that constructor.

A plain object is a runtime value and can carry an application command or a mapped response. A type or interface can describe its shape. A normal TypeScript enum also has a runtime representation, but annotating a field with it does not validate JSON. Use a shared enum or string union only when the layers intentionally share the same meanings; map transport values when they differ.

Choose the representation your contract needs. An empty class for every internal parameter adds files without automatically adding protection.

Follow a login request across the boundaries

This example treats User and Auth as parts of the same identity domain. The application can therefore use the domain User directly. If they were independently owned capabilities, Auth would call a narrow public authentication contract instead of importing Users' internal entity or password hash.

The request first passes a transport validator. The application then loads a user through a repository port, checks the credentials, applies the account-state rule, and requests a session. The controller maps the application result to the response.

1. Let the domain own account rules

The domain has no Nest or ORM imports. A disabled account cannot log in, even if its password is correct. The application supplies the password-verification function, so the entity does not import a hashing library.

export class LoginRejected extends Error {}

// Identity and account-state rules belong to this domain model.
export class User {
  constructor(
    readonly id: string,
    readonly email: string,
    private readonly active: boolean,
    private readonly passwordHash: string,
  ) {}

  assertCanLogin(): void {
    if (!this.active) throw new LoginRejected();
  }

  matchesPassword(
    plain: string,
    verify: (plain: string, hash: string) => Promise<boolean>,
  ): Promise<boolean> {
    return verify(plain, this.passwordHash);
  }
}

For a larger identity model, construction and state changes would protect more invariants. This small example assumes the adapter loads a valid persisted user. A richer reconstitution factory can reject invalid stored states when that is a real requirement.

2. Define the application contract

The use case depends on capabilities, not HTTP or SQL details. It returns the information its caller needs, with no domain entity in the result.

import { LoginRejected, User } from './domain';

export interface UserRepository {
  findByEmail(email: string): Promise<User | null>;
}
export interface PasswordVerifier {
  verify(plain: string, hash: string): Promise<boolean>;
}
export interface SessionIssuer {
  issue(userId: string): Promise<string>;
}
export type LoginCommand = Readonly<{ email: string; password: string }>;
export type LoginResult = Readonly<{
  accessToken: string;
  user: Readonly<{ id: string; email: string }>;
}>;

export class Login {
  constructor(
    private readonly users: UserRepository,
    private readonly passwords: PasswordVerifier,
    private readonly sessions: SessionIssuer,
  ) {}

  async execute(command: LoginCommand): Promise<LoginResult> {
    const user = await this.users.findByEmail(command.email);
    if (!user) throw new LoginRejected();
    const valid = await user.matchesPassword(
      command.password,
      (plain, hash) => this.passwords.verify(plain, hash),
    );
    if (!valid) throw new LoginRejected();
    user.assertCanLogin();
    return {
      accessToken: await this.sessions.issue(user.id),
      user: { id: user.id, email: user.email },
    };
  }
}

The input shape currently matches the request DTO. The separate name makes the application contract explicit, without another class.

TypeScript is structurally typed, so these names alone do not enforce isolation. Import rules and tests can help keep transport dependencies out of the application.

The plain Login class can be registered with a Nest useFactory provider. Wire its repository, verifier, and session adapters there. Interfaces do not work as runtime injection tokens; use explicit tokens where needed. Nest's custom provider documentation covers these provider forms.

3. Keep database details in the adapter

UserRow stands in for the record an ORM returns. Its column names and status representation belong to persistence. The repository port promises a domain User.

import { UserRepository } from './application';
import { User } from './domain';

// Structural stand-in for the persistence record returned by an ORM.
export type UserRow = {
  id: string;
  email: string;
  status: 'active' | 'disabled';
  password_hash: string;
};
export interface UserTable {
  findByEmail(email: string): Promise<UserRow | null>;
}
export class SqlUserRepository implements UserRepository {
  constructor(private readonly table: UserTable) {}

  async findByEmail(email: string): Promise<User | null> {
    const row = await this.table.findByEmail(email);
    return row
      ? new User(row.id, row.email, row.status === 'active', row.password_hash)
      : null;
  }
}

An ORM entity and a domain entity have different jobs.

ORM decorators, lazy relations, database defaults, and change tracking should not become hidden requirements of a framework-free domain model.

For read-only reporting, a query port can return a purpose-built projection instead of rebuilding a full entity. For a small CRUD feature with no meaningful domain behavior, a separate domain class may not be worth maintaining. That still leaves you responsible for controlling the public response.

4. Validate what comes in, map what goes out

The request is a decorated class because this route uses Nest's class-based validation. The response is a type because this example constructs its JSON explicitly and does not use reflection-based response serialization.

import 'reflect-metadata';
import { Body, Controller, HttpCode, Post, UnauthorizedException, ValidationPipe } from '@nestjs/common';
import { IsEmail, IsString, MaxLength, MinLength } from 'class-validator';
import { Login, LoginResult } from './application';
import { LoginRejected } from './domain';

export class LoginRequestDto {
  @IsEmail()
  @MaxLength(254)
  email!: string;

  @IsString()
  @MinLength(1)
  @MaxLength(128)
  password!: string;
}
export const inputPipe = new ValidationPipe({
  transform: true,
  whitelist: true,
  forbidNonWhitelisted: true,
});
export type LoginResponseDto = {
  access_token: string;
  user: { id: string; email: string };
};
export function toResponse(result: LoginResult): LoginResponseDto {
  return {
    access_token: result.accessToken,
    user: { id: result.user.id, email: result.user.email },
  };
}
@Controller('auth')
export class AuthController {
  constructor(private readonly login: Login) {}

  @Post('login')
  @HttpCode(200)
  async execute(@Body(inputPipe) body: LoginRequestDto): Promise<LoginResponseDto> {
    try {
      const result = await this.login.execute({
        email: body.email,
        password: body.password,
      });
      return toResponse(result);
    } catch (error) {
      if (error instanceof LoginRejected) throw new UnauthorizedException();
      throw error;
    }
  }
}

Here, transform returns a DTO instance, whitelist enables checking against validation metadata, and forbidNonWhitelisted rejects extra properties. These options do not replace business rules or authorization. The example's length limits are illustrative input limits; use limits compatible with your real account and password policies.

The mapper names every output field, including the nested user fields. Returning { ...user } or relying on a return-type annotation would not remove extra properties at runtime.

TypeScript's private keyword also does not make an emitted property safe to serialize. Use an explicit projection or a correctly configured serialization strategy, then test the actual output.

LoginRejected becomes an HTTP 401 at the transport boundary. The application itself has no HTTP exception dependency. Unexpected errors still propagate for normal error handling and logging.

This is a boundary example, not a complete authentication implementation.

The runnable tests use fake password, session, and database adapters.

Production authentication also needs a real password verifier and session policy, abuse controls, and review of account-enumeration and timing behavior. The early missing-user return shown here does not equalize password-verification timing. Never log the command's password or the returned token.

Make nested DTOs explicit

A nested TypeScript annotation does not tell a runtime validator how to build or inspect the child object. With this class-based setup, declare the nested validation and transformation together:

import 'reflect-metadata';
import { Type } from 'class-transformer';
import { IsDefined, IsString, MinLength, ValidateNested } from 'class-validator';

export class AddressDto {
  @IsString()
  @MinLength(1)
  city!: string;
}
export class ProfileRequestDto {
  @IsDefined()
  @ValidateNested()
  @Type(() => AddressDto)
  address!: AddressDto;
}
export const toProfileCommand = (dto: ProfileRequestDto) => ({
  address: { city: dto.address.city },
});

@IsDefined() makes the child required. @ValidateNested() checks it, and @Type(() => AddressDto) identifies the nested class for transformation. The class-validator and class-transformer documentation describe those separate responsibilities.

For an array of addresses, also validate that the value is an array and validate each child. When mapping, map each element explicitly if it has a different representation or ownership. A shallow spread leaves nested object references shared.

If an address is a meaningful domain value, the application can construct an Address value object and apply its rules. If it is just a small data shape for this operation, a plain object is enough.

What does User['name'] actually reuse?

An indexed-access type lets a function refer to the type of a property. If User.name is a string, User['name'] is also a string. It carries no minimum length, allowed-character rule, or proof that validation ran.

In a separate module, the two function signatures look like this:

// Separate example module: this User has only a static name shape.
export type User = { name: string };
export function displayName(name: User['name']): User['name'] {
  return name;
}
displayName(''); // Compiles. No length or character rule ran.

export class UserName {
  private readonly brand = 'UserName';
  private constructor(readonly value: string) { Object.freeze(this); }

  static parse(input: unknown): UserName {
    // Example product rule, not a universal rule for people's names.
    if (typeof input !== 'string' || !/^[A-Za-z0-9_]{3,30}$/.test(input)) {
      throw new Error('Invalid user name');
    }
    return new UserName(input);
  }
}
export type DomainUser = { readonly name: UserName };
export function renameInput(name: DomainUser['name']): { name: UserName } {
  return { name };
}
const command = renameInput(UserName.parse('amir_1'));
export const nameResponse = { name: command.name.value };

The first function accepts an empty string because the static shape permits it. The second accepts a UserName value constructed through a runtime factory. The private member prevents an ordinary object with only a value property from satisfying this class type; freezing protects this value from mutation at runtime.

The example rule is for an account handle; it is intentionally not a rule for real human names.

A branded string plus a runtime parsing factory is another option. The brand gives compile-time separation; the factory enforces the rule.

A type assertion can bypass either design's compile-time protection, so casts and external inputs still deserve review. TypeScript readonly and private constructors are compile-time controls, not a security boundary against arbitrary JavaScript mutation.

Once trusted code has constructed a valid value object, it can pass it between internal operations without repeating the same format validation on every call. Rules depending on current state, such as whether an account is still active, may still need checking at the operation that owns them.

Use central types for genuinely shared domain meaning. Avoid a universal User model that owns HTTP fields, database columns, auth secrets, and every module's preferences. An external payload still starts as unknown data: validate and parse it before treating it as a trusted application or domain value.

Reuse a domain type when the contract fits

Reuse a small stable value type when its meaning and representation really match. A public string-union status can be shared if both contracts intentionally use the same values. It still needs runtime validation on untrusted input.

Map when the representations differ. A domain Money containing bigint is not automatically JSON-ready. A date string is not a Date, and a raw string does not become a validated identifier because it has a branded TypeScript annotation. Parse those values at an appropriate boundary.

Avoid turning a domain entity into your public schema with Pick<User, ...> just to save a few declarations. That couples the API to an internal model, and a type projection does not strip fields from an object. Never reuse an ORM entity as a public response merely because its properties happen to match today.

Inside one domain, passing an entity or value object between services is often appropriate. Across a public module boundary, expose the operation and result that the consumer needs. For a queue or external API, define a serializable, versioned contract and validate received data, including vendor responses. DTOs are useful at all of these boundaries.

Catch these mistakes in review

• Treating type, interface, a class field annotation, or as SomeDto as a runtime validator.

• Passing an HTTP DTO through every layer until transport decorators become application dependencies.

• Returning domain or ORM objects directly and assuming a response type hides private fields.

• Repeating the same shape in a new class at every call, without a different contract or useful runtime behavior.

• Moving account-state rules into request validation, or assuming internal calls always passed through the HTTP pipe.

Validation, transformation, mapping, and database access all have costs. Measure them with realistic payloads and request rates before choosing a design for speed. Neither "DTOs are slow" nor "mapping is free" is a useful default. Also consider change cost: how many callers must change when the API, business rule, or database representation changes?

Put the boundary checks to work with NestJS Skills

NestJS Skills already separates entities, value objects, application operations, adapters, and DTOs. It also describes consumer-owned ports and behavioral contracts. That guidance already exists. An automated review still needs to establish how the boundaries work in the project it is reading.

NestJS Skills v2.4.0 now includes executable examples for module contracts, provider wiring, enhancer execution, and runtime/static type boundaries, with 16 new boundary tests. It also corrects three issues: validating and filtering external JSON in the slow-API examples, allowing structurally compatible adapters for abstract-class DI tokens without requiring inheritance, and clarifying that useGlobalFilters() registers supplied instances regardless of whether DI constructed them.

These are focused examples and guidance updates; custom-generator work remains a separate feasibility decision.

For your next review, take one endpoint and follow its input to its output. At each boundary, ask what is trusted, who owns the contract, and which test proves that only the intended data crosses it.

Both endpoints belong to the same NestJS application. The validation already exists. The second endpoint simply takes a path around it.

This is a useful kind of defect to look for during a module-boundary review: a consumer that can change another capability's state without going through the operation that protects its rules.

Define the business rule

For this small example, a charge has two requirements:

• The amount must be a finite, positive number.
• The resulting balance must remain nonnegative.

The storage provider holds the balance. The public operation applies the rules before writing:

@Injectable()
class WalletStorage {
  private balance = 100;

  read() {
    return this.balance;
  }

  write(balance: number) {
    this.balance = balance;
    return { balance };
  }
}

@Injectable()
class WalletOperations {
  constructor(
    @Inject(WalletStorage)
    private readonly storage: WalletStorage,
  ) {}

  charge(amount: number) {
    if (!Number.isFinite(amount) || amount <= 0) {
      throw new BadRequestException('Positive amount required');
    }

    const next = this.storage.read() - amount;

    if (next < 0) {
      throw new ConflictException('Insufficient balance');
    }

    return this.storage.write(next);
  }
}

These excerpts come from a runnable module-boundary example. Imports and bootstrap code are in the linked files. It is an in-memory learning fixture, so the small balance is just test data.

Check whether every consumer uses charge() to change the balance.

Trace the module boundary

The original module exports both providers:

@Module({
  providers: [WalletStorage, WalletOperations],
  exports: [WalletStorage, WalletOperations],
})
class WalletModule {}

In NestJS, providers are encapsulated by their module unless they are made available through its exports. Those exports define what an importing module can inject. NestJS module documentation

Both controllers are registered in AppModule, which imports WalletModule:

@Module({
  imports: [WalletModule],
  controllers: [CheckoutController, BulkController],
})
class AppModule {}

The controllers consume the wallet through another module's exports. A controller registered inside WalletModule could still inject its internal storage provider.

Compare the safe path with the bypass

The checkout controller injects WalletOperations and calls charge(). That path preserves the rule.

The bulk controller injects the lower-level storage provider:

@Controller('bulk')
class BulkController {
  constructor(
    @Inject(WalletStorage)
    private readonly storage: WalletStorage,
  ) {}

  @Post('charge')
  charge(@Body('amount') amount: number) {
    return this.storage.write(this.storage.read() - amount);
  }
}

With a starting balance of 100 and an amount of 150, this method writes -50. Nothing in this path invokes the checks in WalletOperations.

Build a finding from evidence

The defect follows this path:

1. WalletModule exposes a provider that can write the balance directly.
2. BulkController injects that provider.
3. Its handler performs a subtraction and writes the result.
4. The charge rules live in a different operation that this handler never calls.

An exported provider by itself is only a place to investigate. Here, the consumer and the broken rule establish the defect. The original application contains the complete path.

Fix the consumer and the public module API

Two small changes close this path.

Route bulk charges through the public operation

Make the bulk controller use the same public operation as checkout:

@Controller('bulk')
class BulkController {
  constructor(
    @Inject(WalletOperations)
    private readonly wallet: WalletOperations,
  ) {}

  @Post('charge')
  charge(@Body('amount') amount: number) {
    return this.wallet.charge(amount);
  }
}

Remove the storage export

Remove the storage provider from the module's public exports:

@Module({
  providers: [WalletStorage, WalletOperations],
  exports: [WalletOperations],
})
class WalletModule {}

WalletStorage remains available inside WalletModule. Consumers that import the module get the operation that enforces its rules. You can compare the corrected application with the original.

Changing only the controller repairs this consumer but leaves the shortcut available. Removing only the export breaks dependency resolution for the existing consumer. Review and change both sides together.

Why reuse the existing operation?

Copying the checks into the bulk controller would fix this request, but it would create a second place to maintain the same rule.

Moving domain rules into an entity can be useful in a richer model. This fixture already has a small public operation that owns the charge, so reusing it closes the demonstrated path without adding another layer.

Before removing an export in a real project, find all of its consumers. Each caller may need migration, and an exported provider in a published library may already be part of its supported API.

Test through both HTTP paths

A unit test of WalletOperations.charge() can pass while the bulk endpoint remains broken. It proves that the operation rejects an overdraft when called. It does not prove that every endpoint calls it.

The example therefore sends the same invalid charge through both routes:

test('healthy public-operation consumer rejects an overdraft', async () => {
  await request(app.getHttpServer())
    .post('/checkout/charge')
    .send({ amount: 150 })
    .expect(409);
});

test('bulk consumer must preserve the same nonnegative-balance invariant', async () => {
  await request(app.getHttpServer())
    .post('/bulk/charge')
    .send({ amount: 150 })
    .expect(409);
});

The checkout test is a healthy control. It shows that the public operation already handles the case. The bulk test distinguishes the unsafe path from the safe one.

A third test submits a valid checkout charge of 20 and checks that the returned balance is 80. Each test starts a fresh application and closes it afterward, keeping a previous write from affecting the next test. The complete test file includes that setup.

For a stronger application test suite, also verify a successful bulk charge, check that a rejected charge leaves state unchanged, and cover invalid amounts through every public entry point. Those would extend the three checks in this fixture.

Run the example

To run the repository's examples in a fresh checkout with Node.js 20 or later:

git clone https://github.com/amirtaherkhani/nestjs-skills.git
cd nestjs-skills
git checkout 96fb9a22c59a54fa1250a2664455c71df4942dfc
npm ci
npm run test:fixtures

The pinned revision keeps the example aligned with this article. The command above runs all three learning fixtures. The runner expects the original versions to fail their seeded regression checks and the corrected versions to pass. An unexpected result fails the runner.

What the tests verified

For this article, the TypeScript examples were compiled and the existing module-boundary test file was run against each wallet version on Node.js 24.11.0, NestJS 11.2.7, and TypeScript 5.9.3:

The original version has two passes and one intentional failure; the corrected version has three passes. Only the wallet HTTP tests were executed for this article review. These results verify the fixture's behavior, not the effectiveness of an AI review tool.

Scope and limits

The repair gives this example a narrower module API and routes both charge endpoints through the same checks.

It does not establish that every storage provider in every NestJS application should be hidden. Some exported providers are intentionally shared infrastructure or a carefully designed read interface. Review the operations they expose, their consumers, and the rules those consumers must preserve.

The example has one in-memory balance and synchronous writes. A real persisted wallet needs its own decisions about atomic updates, concurrent requests, authorization, numeric representation, and retry behavior.

Removing a module export does not solve those concerns. Nest module encapsulation controls dependency injection; it is not a security sandbox against code running in the same process.

Apply the review method to your own codebase

Choose one business rule and trace every path that can change the state it protects:

• Where is the rule enforced?
• Which providers can write the underlying state?
• Which of those providers are exported?
• Do any consumers reach the write without passing through the rule?
• Which boundary test would demonstrate that behavior?

Then describe the finding with the call path, observable impact, smallest correction, and regression test. That gives a reviewer enough information to check your conclusion.

Key takeaways

• Trace a write from the consumer to the business rule before reporting a module-boundary defect.
• Repair both the bypassing consumer and the module API that exposes the shortcut.
• Test every relevant entry point: a passing operation test cannot prove that a controller calls it.

A tool for repeating this review

The nestjs-code-audit skill provides a read-only workflow for collecting and reporting this evidence. You can ask it to trace exported providers and their consumers, identify invariant bypasses, and propose a regression test without changing code. Each finding still needs to hold up against the application.

The NestJS Skills documentation explains how to install the skills and choose the right one for a specific engineering task.