Clean and hexagonal architecture

The problem

In many applications, business rules are tangled with framework code, SQL and HTTP details. Then:

• You cannot test a rule without a database and a web server.
• Changing a framework or database means rewriting business logic.
• The code is organised around technology, not around what the system does.

Several architectures (hexagonal, onion, clean) solve this with the same idea: put business rules at the centre and keep details at the edges.

The dependency rule

100%

Figure SDA-SDE-06-1 · Clean architecture: dependencies point inwards · © forcsguy.com

Source code dependencies point inwards only. Entities know nothing about use cases; use cases know nothing about the web or the database. Outer layers depend on inner ones, never the reverse.

Layer	Contains	Knows about
Entities	Core business objects and rules that would exist whatever the technology	Nothing else
Use cases	Application-specific actions ("place order", "cancel subscription") that coordinate entities	Entities and the ports they define
Interface adapters	Controllers, presenters, repositories' implementations, mappers	Use cases
Frameworks and drivers	The web framework, database, message queue, UI	Adapters

Ports and adapters (hexagonal)

The application is the hexagon. It talks to the outside only through ports: interfaces it owns. Adapters translate between the outside world and the ports.

• Driving (inbound) ports: how the world calls the application (PlaceOrder). Adapters: REST controller, CLI, message listener, test.
• Driven (outbound) ports: what the application needs (OrderRepository, PaymentGateway, Clock). Adapters: SQL implementation, payment provider client, fake for tests.

// Port owned by the application
interface OrderRepository { save(order: Order): Promise<void>; byId(id: string): Promise<Order | null> }
interface PaymentGateway { charge(cents: number, token: string): Promise<boolean> }

// Use case: pure application logic
class PlaceOrder {
  constructor(private orders: OrderRepository, private payments: PaymentGateway) {}
  async run(input: { items: Item[]; token: string }) {
    const order = Order.create(input.items);                   // entity enforces rules
    if (!(await this.payments.charge(order.totalCents, input.token))) throw new Error("Payment failed");
    await this.orders.save(order);
    return order.id;
  }
}

// Adapters live outside, implementing the ports
class SqlOrderRepository implements OrderRepository { /* uses a database */ }
class StripeGateway implements PaymentGateway { /* calls the provider */ }

// Composition root wires everything together at start-up
const placeOrder = new PlaceOrder(new SqlOrderRepository(db), new StripeGateway(key));

This is the dependency inversion principle from SOLID applied to a whole system.

Benefits

• Testable: run use cases with in-memory fakes, fast and without infrastructure.
• Replaceable details: change the database, queue or web framework by writing an adapter.
• Focus on the domain: the central code reads like the business process.
• Deferred decisions: you can postpone choosing a database.

Costs and cautions

• More structure: interfaces, mappers and wiring add code. For a small CRUD app it can be overkill.
• Mapping between layers (domain objects, database rows, API shapes) is repetitive; do it deliberately and avoid leaking database entities into the API.
• Do not create layers "because the diagram says so". Add a boundary where a real change or testing need exists.
• It is about dependencies, not folder names: a good folder layout helps but does not guarantee the rule is followed. Enforce it with tests or lint rules.

Related ideas

• Domain-driven design supplies the language for the centre of the hexagon (next lesson).
• Microservices are a deployment choice; each service can use this internal structure.
• Composition root: one place, at start-up, where concrete classes are chosen and injected.

Real-world reading