Hexagonal Architecture in Node

// domain/ports/notification-port.ts
export interface NotificationPort {
  send(to: string, body: string): Promise<void>;
}
 
// application/place-order.ts
export class PlaceOrder {
  constructor(
    private readonly orders: OrderRepository,
    private readonly notifications: NotificationPort
  ) {}
 
  async execute(input: { customerId: string; sku: string }) {
    const order = { id: crypto.randomUUID(), ...input };
    await this.orders.save(order);
    await this.notifications.send(input.customerId, `Order ${order.id} placed`);
    return order;
  }
}

// src/modules/billing/domain/ports/invoice-repository.ts
export type Invoice = { id: string; customerId: string; amountCents: number };
 
export interface InvoiceRepository {
  save(invoice: Invoice): Promise<void>;
}
 
// src/modules/billing/domain/ports/payment-gateway.ts
export interface PaymentGateway {
  charge(customerId: string, amountCents: number): Promise<{ chargeId: string }>;
}
 
// src/modules/billing/application/charge-invoice.ts
export class ChargeInvoice {
  constructor(
    private readonly invoices: InvoiceRepository,
    private readonly payments: PaymentGateway
  ) {}
 
  async execute(invoiceId: string) {
    // load, charge, persist - no HTTP types here
    const invoice = { id: invoiceId, customerId: "c1", amountCents: 5000 };
    const { chargeId } = await this.payments.charge(invoice.customerId, invoice.amountCents);
    await this.invoices.save({ ...invoice, id: chargeId });
    return { invoiceId, chargeId };
  }
}
 
// src/modules/billing/infrastructure/http/routes.ts
import express from "express";
import type { ChargeInvoice } from "../../application/charge-invoice";
 
export function billingRouter(chargeInvoice: ChargeInvoice) {
  const router = express.Router();
  router.post("/invoices/:id/charge", async (req, res, next) => {
    try {
      const result = await chargeInvoice.execute(req.params.id);
      res.json({ data: result });
    } catch (err) {
      next(err);
    }
  });
  return router;
}
 
// src/modules/billing/infrastructure/stripe-payment-gateway.ts
import type { PaymentGateway } from "../../domain/ports/payment-gateway";
 
export class StripePaymentGateway implements PaymentGateway {
  async charge(customerId: string, amountCents: number) {
    return { chargeId: `ch_${customerId}_${amountCents}` };
  }
}
 
// src/main.ts - composition root
import express from "express";
import { ChargeInvoice } from "./modules/billing/application/charge-invoice";
import { billingRouter } from "./modules/billing/infrastructure/http/routes";
import { StripePaymentGateway } from "./modules/billing/infrastructure/stripe-payment-gateway";
 
const chargeInvoice = new ChargeInvoice(
  { save: async () => {} },
  new StripePaymentGateway()
);
 
const app = express();
app.use(express.json());
app.use("/billing", billingRouter(chargeInvoice));
app.listen(3000);

src/modules/billing/
├── domain/
│   ├── invoice.ts
│   └── ports/
│       ├── invoice-repository.ts
│       └── payment-gateway.ts
├── application/
│   └── charge-invoice.ts
└── infrastructure/
    ├── http/routes.ts
    ├── postgres-invoice-repository.ts
    └── stripe-payment-gateway.ts

// Prefer small port interfaces - easier to fake in tests
export interface Clock {
  now(): Date;
}
 
export class ExpireSessions {
  constructor(private readonly clock: Clock) {}
  isExpired(createdAt: Date, ttlMs: number): boolean {
    return this.clock.now().getTime() - createdAt.getTime() > ttlMs;
  }
}
 
// Test double
const fixedClock: Clock = { now: () => new Date("2026-01-01T00:00:00Z") };