The Shift from Layered to Hexagonal Thinking
Most developers start their Node.js journey with the standard MVC pattern. You have routes, controllers, services, and models stacked on top of each other. This works for a weekend project. However, as your codebase grows to 10,000+ lines, you might notice business logic bleeding into database queries. Suddenly, your services are tightly coupled to Express or a specific version of TypeORM.
Hexagonal Architecture, or Ports and Adapters, flips this structure. Think of your application core as a high-end stereo system. The speakers (database) and the input (Express, CLI, or Cron jobs) are just components you plug into the back. The core doesn’t care who manufactured the speakers; it just sends a signal through a standardized jack. Adopting this mindset prevents your project from becoming a legacy nightmare that is too scary to refactor.
Layered vs. Hexagonal: A Comparison
In a standard Layered Architecture, the dependency flow is rigid: Controller -> Service -> Repository -> Database. If you swap MongoDB for PostgreSQL, you often end up rewriting 30% of your Service layer because it expects a specific data shape. The business logic is essentially a hostage of the infrastructure.
Hexagonal Architecture breaks this chain. The Core (Domain) defines “Ports”—simple interfaces that describe what the app needs to do. The Infrastructure (Adapters) then implements those interfaces. Your core logic remains blissfully unaware of whether it is talking to a real database, a CSV file, or a mock for testing.
Pros and Cons of the Hexagonal Approach
Architecture is always a trade-off. Before you refactor your entire repository, consider if the benefits outweigh the overhead for your specific use case.
The Benefits
- Framework Agnostic: You can swap Express for Fastify in an afternoon. You could even run the same logic in an AWS Lambda function without touching a single line of business code.
- Blazing Fast Testing: Since the logic is isolated, unit tests don’t need to wait for a database connection or a server boot-up. These tests often run in milliseconds rather than seconds.
- Vendor Lock-in Protection: If your email provider doubles their prices, you only change one adapter file. The rest of your system stays exactly the same.
The Trade-offs
- Initial Overhead: You will write more code at the start. A simple feature that used to take two files might now require five or six.
- Data Mapping: You have to convert database entities into domain models. This prevents database schemas from leaking into your logic but adds a layer of boilerplate.
- Cognitive Load: New team members might find the separation of concerns confusing if they are only used to traditional MVC.
Recommended Folder Structure
A clear directory structure is the best way to enforce these boundaries in Node.js. Here is a layout that has proven resilient in production environments:
src/
├── domain/ # Pure logic (Entities, Value Objects, Domain Errors)
├── application/ # Use cases and Port definitions (Interfaces)
├── infrastructure/ # Adapters (TypeORM, Axios, Express, NestJS)
└── main.ts # The "Composition Root" where everything is wired up
Step-by-Step Implementation Guide
Let’s build a User Registration feature. We will use TypeScript because its interface system is the perfect tool for defining Ports.
1. The Domain Entity
The domain is the heart of your application. It should have zero dependencies on external libraries. If you can’t run this file in a plain Node.js script, it’s probably too coupled.
// src/domain/user.ts
export class User {
constructor(
public readonly id: string,
public readonly email: string,
public readonly passwordHash: string
) {}
// Business rules live here, not in the controller
public hasValidEmail(): boolean {
return this.email.includes('@') && this.email.length > 5;
}
}
2. Defining the Port (The Interface)
The port lives in the application layer. It acts as a contract. It tells the outside world: “To work with this app, you must provide a way to save and find users.”
// src/application/ports/user-repository.port.ts
import { User } from '../../domain/user';
export interface UserRepository {
save(user: User): Promise<void>;
findByEmail(email: string): Promise<User | null>;
}
3. The Application Use Case
The use case orchestrates the logic. Note that it only knows about the UserRepository interface. It has no idea if the data ends up in MongoDB or a JSON file.
// src/application/use-cases/register-user.ts
import { User } from '../../domain/user';
import { UserRepository } from '../ports/user-repository.port';
export class RegisterUser {
constructor(private userRepository: UserRepository) {}
async execute(email: string, passwordHash: string): Promise<void> {
const existingUser = await this.userRepository.findByEmail(email);
if (existingUser) {
throw new Error('This email is already registered');
}
const user = new User(crypto.randomUUID(), email, passwordHash);
await this.userRepository.save(user);
}
}
4. The Infrastructure Adapter
This is where the heavy lifting happens. We implement the actual database logic using our preferred tools.
// src/infrastructure/adapters/repositories/mongo-user-repository.ts
import { UserRepository } from '../../../application/ports/user-repository.port';
import { User } from '../../../domain/user';
export class MongoUserRepository implements UserRepository {
async save(user: User): Promise<void> {
// Imagine Mongoose logic here
console.log(`Persisting ${user.email} to MongoDB collection...`);
}
async findByEmail(email: string): Promise<User | null> {
// Database lookup logic
return null;
}
}
5. Wiring It Together
The final step happens at the entry point of your app. You inject the concrete adapter into the use case.
// src/main.ts
import { RegisterUser } from './application/use-cases/register-user';
import { MongoUserRepository } from './infrastructure/adapters/repositories/mongo-user-repository';
// Dependency Injection
const userRepository = new MongoUserRepository();
const registerUserUseCase = new RegisterUser(userRepository);
// This can now be called by an Express route, a CLI, or a test suite
registerUserUseCase.execute('[email protected]', 'secure_hash_123')
.then(() => console.log('Success!'))
.catch(err => console.error('Failed:', err.message));
Lessons from Production
Moving to this architecture often brings up specific challenges. Here is how to handle them without losing your mind.
The Mapping Trap
A common mistake is passing database models—like Mongoose or Sequelize objects—directly into your business logic. This creates a hidden dependency that defeats the whole purpose. Always map your database results to your Domain Entities inside the Adapter. It feels like redundant work until the day you need to change your database schema without breaking your tests.
Managing Dependencies
While manual instantiation works for small apps, it becomes tedious as you add more services. For larger projects, use a Dependency Injection (DI) container like InversifyJS or Awilix. These tools automate the wiring process, making it easier to swap adapters for different environments.
Avoid Over-Engineering
If you are building a simple CRUD API with three endpoints that will likely be deleted in three months, Hexagonal Architecture is overkill. Use this pattern when the business logic is complex or when you expect the project to be maintained by a team for several years. The goal is a state where your business logic is so pure that you can test it, move it, or scale it without fighting your own infrastructure.
