The Hexagon

Hexagonal architecture (Alistair Cockburn) inverts the usual layering: instead of domain depending on database, the database depends on the domain. The domain declares ports (interfaces); the outside world provides adapters (implementations).

Result: you can swap Postgres for in-memory in tests, or HTTP for a CLI, without touching a single domain class.

Domain at the centre; each side of the hexagon is a port with one or more adapters.

Worked example — sketching the hexagon in PlantUML.

PlantUML is a tiny text DSL: every diagram starts with @startuml and ends with @enduml. Inside, package groups related things and interface / class declare types. An arrow ..> means depends on:

@startuml
package "domain" {
  interface OrderRepository
  class Order
}

package "infrastructure" {
  class PostgresOrderRepository
}

PostgresOrderRepository ..|> OrderRepository : implements
PostgresOrderRepository ..> Order            : uses
@enduml

The two rules you must keep visible in your diagram:

1. The interface lives in domain, not in infrastructure. That's the port — owned by the high-level policy.
2. Every arrow crosses from infrastructure into domain, never the other way. If you ever need an arrow pointing out of domain, your hexagon is broken.