Hexagonal architecture (ports & adapters) template

Keep business logic independent: driving adapters call inbound ports, the core uses outbound ports that adapters implement.

Use this templateFree, opens in your browser. No sign-up.

Hexagonal architecture (ports & adapters) template
Driving adapters (inbound)
Application core
Driven adapters (outbound)
REST controller
CLI / admin tool
Message consumer (Kafka)
Port: PlaceOrder (use case)
Port: GetOrderStatus
OrderService implements the use cases
Domain model: Order, LineItem, Money + rules
Port: OrderRepository
Port: PaymentGateway
Port: Notifier
PostgreSQL repository
Stripe client
Email sender (SES)
Dependencies point inward: the core never imports adapters. Swap Postgres or Stripe without touching business rules.
Test the core with in-memory adapters: fast, no database.
Hexagonal architecture
implemented by
The hexagonal architecture (ports & adapters) template as it opens in Kelvo: 13 boxes, 2 sticky notes and 12 links, in 3 sections.

What is hexagonal architecture?

Hexagonal architecture, also called ports and adapters, was described by Alistair Cockburn in 2005. It keeps the business logic in an application core that doesn't depend on any framework, database or vendor. The core defines ports: interfaces for what it offers (inbound, such as a PlaceOrder use case) and for what it needs (outbound, such as an OrderRepository or a PaymentGateway). Adapters outside the core connect real technology to those ports.

The template draws the three zones. Driving adapters (a REST controller, a CLI admin tool and a Kafka message consumer) call the inbound ports. The core holds the domain model (Order, LineItem, Money) and an OrderService that implements the use cases. Driven adapters (a PostgreSQL repository, a Stripe client and an SES email sender) implement the outbound ports. The rule written on the board: dependencies point inward.

What's on the board

Driving adapters (inbound)
REST controller · CLI / admin tool · Message consumer (Kafka)
Application core
Port: OrderRepository · Port: PlaceOrder (use case) · OrderService implements the use cases · Port: PaymentGateway · Domain model: Order, LineItem, Money + rules · Port: GetOrderStatus · Port: Notifier
Driven adapters (outbound)
PostgreSQL repository · Stripe client · Email sender (SES)

Also on the board

  • Dependencies point inward: the core never imports adapters. Swap Postgres or Stripe…
  • Test the core with in-memory adapters: fast, no database.

How to fill in the hexagonal architecture (ports & adapters) template

  1. Click Use this template. It opens in the Kelvo app as a new board, saved in your browser. Double-click any box to change its text.
  2. Name your use cases. Replace PlaceOrder and GetOrderStatus with the actions your application offers. Each one becomes an inbound port.
  3. List what the core needs. Add an outbound port for each external dependency: storage, payments, messaging, email. Name ports by what the core needs (Notifier), not by technology (SES).
  4. Put adapters on both sides. Add the controllers and consumers that drive your application on one side, and the databases and services it drives on the other. Link each adapter to its port.
  5. Check the dependency rule. Every link between the core and an adapter should point inward. If the domain model mentions a framework or an SDK, move that code into an adapter.
  6. Plan the test adapters. Add in-memory versions of the outbound adapters, so the core can be tested in milliseconds without a database.

When to use it

  • Business logic that should outlive its frameworks, databases or vendors
  • You want fast tests of the core with in-memory adapters and no database
  • Explaining a codebase's boundaries to new engineers

When to skip it

  • Thin CRUD services, where the extra interfaces add more code than they save
  • Prototypes you expect to throw away

Working on an architecture diagram in Kelvo

Sketch, then convert
Draw boxes and arrows with the pen, select the strokes and click Convert sketch: they become real boxes and links.
Ask Kelvo right on the board (Pro)
With Pro, type @kelvo and what you want in any box or text, for example “@kelvo add error handling”, and press Enter. The change is made there and the request disappears; ⌘Z undoes it.

Questions

Why is it called hexagonal?

Alistair Cockburn drew the application as a hexagon to leave room for several ports and adapters around it, and to break the habit of drawing layers from top to bottom. The six sides have no special meaning; “ports and adapters” is the more descriptive name.

How is hexagonal architecture different from clean or onion architecture?

They share the same idea: business logic in the centre, dependencies pointing inward, infrastructure at the edges. Onion and clean architecture name more layers inside the core, such as entities and use cases; hexagonal architecture focuses on the ports and adapters at the boundary.

What's the difference between a port and an adapter?

A port is an interface owned by the core, such as OrderRepository. An adapter is an implementation that connects that port to real technology, such as a PostgreSQL repository, or to an in-memory store for tests.

Related templates

  • CQRS + event sourcing template previewCQRS + event sourcing

    Separate write and read paths: commands append events to an event store, projectors build read models for queries.

  • Layered (n-tier) architecture template previewLayered (n-tier) architecture

    Presentation, application, domain, persistence and database layers, with cross-cutting concerns and the rules that keep layers clean.

  • C4 system context diagram template previewC4 system context diagram

    C4 level 1: the system in scope, the people who use it and the external systems it depends on, with a legend.

  • C4 container diagram template previewC4 container diagram

    C4 level 2: the apps, APIs, databases and queues inside the system boundary, with the technology on each link.

  • Microservices with API gateway template previewMicroservices with API gateway

    Clients behind an API gateway, services that each own their database, and an event bus for asynchronous work.

  • LLM application architecture template previewLLM application architecture

    Production building blocks around a model: gateway, guardrails, orchestrator, cache, vector DB, tools and observability.

All solution architecture diagram templates · All templates

Use the hexagonal architecture (ports & adapters) template