Building Maintainable Backends with Port-Adapter Architecture in NestJS

TL;DR

Port-Adapter Architecture helps keep business logic separate from infrastructure like databases and external services, making your NestJS app easier to test and change. Use it only where flexibility matters, not everywhere.

Introduction

When we start backend development, most of us write code like this:

Controller calls Service
Service directly talks to Database
Service also calls email, SMS, payment, etc.

This works fine at the beginning. But as the project grows, things slowly become messy. One small change breaks many places. Testing becomes hard. New developers feel lost.

This is where Port-Adapter Architecture (also known as Hexagonal Architecture) helps. It is not magic and not mandatory everywhere, but when used correctly, it makes backend code clean, understandable, and future-proof.

In this article, we will understand:

What Port-Adapter Architecture really is (in simple words)
Why and when to use it
How it compares to other approaches
A clear folder structure
When NOT to use ports

What Problem Are We Actually Solving?

Imagine this service code:

// ProductService
await this.productModel.create(data);
await axios.post("email-service/send");
await redis.set(key, value);

Problems here:

Database logic inside service
External API logic inside service
Hard to test
Hard to replace MongoDB or email provider
Too many responsibilities in one place

This creates tight coupling. Tight coupling makes future changes painful.

What is Port-Adapter Architecture (Hexagonal Architecture)?

Port-Adapter Architecture separates thinking from doing.

Port = What the application needs (interface)
Adapter = How it is actually done (real implementation)

Example:

"I need to save a product" → Port
"I save it using MongoDB" → Adapter

If tomorrow you want PostgreSQL, you only change the adapter. Business logic stays the same.

Why Port-Adapter vs Other Common Approaches?

1. Traditional Service → Repository (No Ports)

Controller → Service → Repository

This approach is completely fine for:

Small applications
MVPs
Side projects

But it becomes a problem when:

Service depends on many external systems
Testing requires mocking many things
You want to replace implementations

2. Clean Architecture

Clean Architecture is powerful, but:

Too many layers
Too much boilerplate
Hard for beginners
Slower development for small teams

3. Why Port-Adapter is a Good Balance

Port-Adapter gives:

Clear boundaries
Less coupling
Easier testing
Flexibility

Without being too complex or academic.

Important Rule: Ports Are NOT Required for Everything

This is very important.

Do NOT create ports for:

Simple CRUD repositories
Internal helper services
Utility functions
Logic that will never change

Use ports for:

External services (email, SMS, payment)
Cross-module dependencies
Business-critical operations
Things that may change in the future

Architecture should reduce complexity, not increase it.

Beginner-Friendly Folder Structure

src/
│
├── product/
│   ├── controllers/
│   │   └── product.controller.ts
│   │
│   ├── services/
│   │   └── product.service.ts
│   │
│   ├── ports/
│   │   └── product.port.ts
│   │
│   ├── repositories/
│   │   └── product.repository.ts
│   │
│   ├── dto/
│   │   ├── create-product.dto.ts
│   │   └── update-product.dto.ts
│   │
│   ├── schemas/
│   │   └── product.schema.ts
│   │
│   ├── product.tokens.ts
│   └── product.module.ts
│
├── inventory/
│   ├── ports/
│   ├── services/
│   └── inventory.module.ts
│
├── notification/
│   ├── ports/
│   ├── services/
│   └── notification.module.ts
│
└── common/
    ├── base/
    ├── utils/
    └── constants/

Why This Structure Works

Easy for new developers to understand
Clear separation of responsibilities
Business logic is easy to find
Infrastructure code is isolated

Where Ports Make the Most Sense

A very common and practical example is payment or transaction handling.

Imagine your application needs to process payments. Today you might use Stripe, but tomorrow the business may ask to support another payment partner like Khalti, Esewa, or any other gateway.

If you directly write Stripe code inside your service, changing the payment provider later will be painful and risky.

This is where a port makes perfect sense.

Payment Port Example

// payment.port.ts
export interface PaymentPort {
  charge(
    amount: number,
    currency: string,
    source: string
  ): Promise<PaymentResult>;
}

Stripe Adapter

@Injectable()
export class StripePaymentAdapter implements PaymentPort {
  async charge(amount: number, currency: string, source: string) {
    // Stripe-specific implementation
  }
}

Another Payment Adapter (Future)

@Injectable()
export class EsewaPaymentAdapter implements PaymentPort {
  async charge(amount: number, currency: string, source: string) {
    // Esewa-specific implementation
  }
}

Service Using the Port

constructor(
  @Inject(PAYMENT_SERVICE)
  private readonly paymentService: PaymentPort,
) {}

Now your business logic does not care whether the payment is done by Stripe, Esewa, or any other provider. You can switch implementations from the module without touching the service code.

This is an ideal and real-world use case for Port-Adapter Architecture.

When You Should Avoid Ports

If your code is:

await this.userRepository.findById(id);

And:

Repository is local
No external dependency
No plan to replace it

Then do not create a port. Keep it simple.

Simple Mental Model

Before creating a port, ask:

"Will I ever want to replace or mock this?"

Yes → Use a port
No → Do not use a port

Conclusion

Port-Adapter Architecture is a tool, not a rule.

Use it when:

Project is growing
Multiple developers are working together
Business logic is important
Testing matters

Avoid it when:

Application is small
Logic is simple
Abstraction adds confusion

In NestJS, this pattern fits naturally and helps keep code clean without becoming too complex. Start small and apply it only where it makes sense.