You start a NestJS project with good intentions. Six months later, users.service.ts imports TypeORM, sends emails, hashes passwords, and publishes Kafka events. Changing the database feels like surgery.
That is not a team problem. It is an architecture problem — and hexagonal architecture (ports and adapters) is one of the most effective fixes for backend teams that outgrow the classic controller → service → entity stack.
This article walks through the model used in the NestJS Enterprise Starter, with enough detail that you can apply it in your own codebase this week.
The real cost of a "simple" service layer
When business logic, HTTP, and persistence live in the same class:
- Tests need Postgres — slow feedback, skipped tests, regressions in production.
- Framework lock-in — TypeORM decorators become your "domain model."
- Controllers grow fat — validation, hashing, and side effects end up in
@Post() handlers.
Hexagonal architecture draws a line: the center is your business rules; everything else is a plugin you can replace.
The picture that actually helps
Imagine your app as a hexagon:
- Driving adapters push work in: REST controllers, GraphQL, CLI, queue consumers.
- Driven adapters are called by the core: PostgreSQL, Redis, Stripe, SendGrid.
- Ports are TypeScript interfaces the core defines — "I need to save a user," not "I use TypeORM."
HTTP → Application (use cases) → Domain
↑
TypeORM repo implements UserRepositoryPort
The rule is simple: dependencies point inward. core/ never imports @nestjs/common or typeorm.
A folder structure you can adopt tomorrow
src/
├── core/
│ ├── domain/
│ └── ports/output/persistence/
├── application/
│ └── commands/user/
├── adapters/
│ ├── primary/http/
│ └── secondary/persistence/typeorm/
└── modules/user/
NestJS modules become wiring only: they bind UserRepositoryPort → UserRepository. Handlers depend on the port; the module chooses the adapter.
Ports: contracts, not implementations
The domain declares what it needs:
export abstract class UserRepositoryPort {
abstract findByEmail(email: string): Promise<User | null>;
abstract create(payload: CreateUserPayload): Promise<User>;
}
No @Injectable(), no Repository<UserOrmEntity>. The handler asks for a capability; NestJS injects the implementation at runtime.
Adapters: where frameworks live
The TypeORM entity stays in adapters/secondary:
@Entity('users')
export class UserOrmEntity {
@PrimaryGeneratedColumn('uuid')
id: string;
@Column({ unique: true })
email: string;
// ...
}
A mapper translates ORM → domain:
static toDomain(orm: UserOrmEntity): User {
return { id: orm.id, email: orm.email, name: orm.name, ... };
}
Handlers never see UserOrmEntity. When you migrate to Prisma, you rewrite one adapter — not forty use cases.
Controllers should translate, not decide
Bad:
@Post()
async create(@Body() dto: CreateUserDto) {
const hash = await bcrypt.hash(dto.password, 10);
return this.repo.save({ ...dto, password: hash });
}
Good:
@Post()
create(@Body() dto: CreateUserDto) {
return this.commandBus.execute(new CreateUserCommand(dto));
}
Password rules, duplicate email checks, and welcome emails belong in a command handler in the application layer.
What you gain in practice
| Benefit |
What it feels like day to day |
| Fast unit tests |
Handlers tested with jest.fn() mocks — no Docker |
| Swappable infra |
New queue or DB = new adapter + provider |
| Onboarding |
Juniors know where code belongs |
| Reuse |
Same handler from HTTP, cron, or BullMQ worker |
Mistakes I see in every audit
- ORM entities in
core/ — move them to adapters; map to plain types.
- Injecting concrete
UserRepository in handlers — inject UserRepositoryPort.
- "Just this once" logic in the controller — it never stays once.
Where to go next
Hexagonal layout pairs naturally with CQRS (separate read and write paths) and ports for queues (BullMQ behind IQueueService). In this series, we cover those patterns next — same repo, same dependency direction.
If you are building a NestJS API that must survive more than one hiring cycle, start by extracting one module (Users) into ports and adapters. You will feel the difference in the first week of tests.
