hexagonal-pattern-guide

Hexagonal Architecture (Ports and Adapters)

Isolate the domain core behind ports it owns, so every I/O and delivery mechanism is an interchangeable adapter on the outside.

Essentials

• Driving in, driven out - primary adapters call into the core; secondary adapters are called out by it, see references/ports-and-adapters.md
• Dependencies point inward - the core names no adapter; the dependency rule + dependency inversion, see references/dependency-inversion.md
• Wiring lives in one composition root - see references/composition-root.md
• Testability is the payoff - fake the driven adapters, drive the core in a test, no real I/O, see references/testability.md

Gotchas

• The hexagon isn't six of anything. It just signals "many ports", not a top/bottom layering.
• Ports-and-adapters is not the microkernel pattern: hexagonal isolates the domain behind a usually-fixed set of ports; an open, registered plug-in set is microkernel-pattern-guide. They share the adapter mechanism, nothing more.
• If a unit test needs a real database or network, the boundary leaked: narrow the port or invert the dependency.

Example

// core owns the port; it never imports a driver
type Repository interface{ Save(o Order) error }

type OrderService struct{ repo Repository } // depends on the port, not Postgres

// driven adapter (outside): a PostgresRepository implementation of the port
// driving adapter (outside): an HTTP handler that calls OrderService
// test: an InMemoryRepository fake, no database

Progressive Disclosure

• Read references/ports-and-adapters.md - Load when defining ports and driving/driven adapters around a core
• Read references/dependency-inversion.md - Load when deciding which way dependencies point or detecting a core leak
• Read references/composition-root.md - Load when wiring concrete adapters to ports in one place
• Read references/testability.md - Load when testing a core in isolation with fakes/test doubles