Skip to content

CONCEPT Cited by 1 source

Hexagonal architecture

Definition

Hexagonal architecture (Alistair Cockburn, 2005), also known as ports-and-adapters, organizes a codebase into concentric layers where the innermost domain holds business rules with no external dependencies, and every integration with the outside world (databases, queues, HTTP, file systems, cloud SDKs) enters through a named port (an interface) implemented by an adapter (the integration code). The domain depends on ports it defines; adapters depend on ports. Nothing in the domain depends on any adapter.

Contrast with a naive three-tier layering where the domain imports aws-sdk directly — in hexagonal, the domain imports a UserRepository port, and a DynamoDbUserRepository adapter implements it.

Canonical layout named by AWS 2026-03-26

The 2026-03-26 AWS Architecture Blog post prescribes the hexagonal shape as the codebase precondition for agentic development:

"A domain-driven structure inspired by Domain-Driven Design (DDD) separates core business logic from application orchestration and infrastructure concerns. In practice, this often means organizing code into predictable layers such as /domain, /application, and /infrastructure. The domain layer contains business rules with no Amazon dependencies. Infrastructure code handles integrations with services such as Amazon DynamoDB or Amazon SNS. This separation allows AI agents to modify business logic and validate it locally without touching cloud-specific code."

"Patterns like hexagonal architecture reinforce this separation by treating external systems as adapters rather than dependencies."

Why agents benefit

  • Domain layer is testable without the cloud. Unit tests for business rules need no SDK, no credentials, no emulator — they run at millisecond latency, which is the tier agents iterate at.
  • Changes have known blast radius. A domain-logic edit cannot accidentally rewrite cloud-integration code; the dependency direction is enforced by the layer boundary.
  • Local emulation and production deploy share the same ports. Swap adapters (in-memory repository for tests, DynamoDB adapter in production) without touching domain or application code.

Canonical layer set

Layer Holds Depends on
/domain business rules, value objects, domain services, port interfaces nothing
/application orchestration, use cases, transaction boundaries /domain
/infrastructure adapters (DB, queue, HTTP, SDK), bootstrap /domain, /application

Failure modes without it

  • Domain code imports aws-sdk; agent can't validate business logic without cloud credentials.
  • A "repository" directly constructs a DynamoDBClient; swapping for a systems/dynamodb-local test requires a code edit rather than a config change.
  • Layer boundaries exist in names only; direction of dependency is not enforced, and rot compounds over time.

Seen in

Last updated · 200 distilled / 1,178 read