What problem are we solving?

Illustrative composite. An eligibility application began as a web portal backed by one identity service and one household-data provider. It now has three ways to start the same decision: the customer portal, a nightly enrollment batch, and a support console. A second provider is replacing the first one region by region.

The eligibility rules are mixed into portal controllers and provider clients. A policy test needs credentials for a shared sandbox. The batch job reimplements validation because the portal flow cannot be called without HTTP. Provider timeouts surface as “insufficient evidence,” which makes a technical outage look like a business outcome.

The system has two sources of friction. Different outside actors need to invoke the same business behavior, and different outside services need to supply the same kinds of facts. The application has no stable way to describe either conversation in its own terms.

What is this practice?

Hexagonal Architecture lets the application define the conversations it needs with people, programs, storage, and external services. Technology-specific code translates those conversations at the boundary, so the business behavior is not written in the language of a portal framework, a batch format, a database client, or a provider SDK.

Alistair Cockburn's original description of Hexagonal Architecture frames the goal practically: an application should be drivable by users, programs, automated tests, or batch scripts and should be testable without its production database or devices.

The formal vocabulary describes direction:

  • A driving port is an application operation an outside actor can request.
  • A driving adapter translates a portal request, batch row, support action, or test into that operation.
  • A driven port describes something the application needs from the outside, such as household facts or decision storage.
  • A driven adapter translates that need into a database call, provider request, or queue message.

The hexagon is a drawing convention, not a requirement for six sides, six layers, or six projects. The useful boundary is between the application's conversations and the technologies participating in them.

How does it change the work?

Give the application one operation for the eligibility decision:

type EvaluateEligibility =
  (request: EligibilityRequest) -> EligibilityOutcome

type EligibilityOutcome =
  | Eligible { decision: Decision }
  | Ineligible { reasons: Reason[] }
  | MoreEvidenceRequired { requests: EvidenceRequest[] }
  | TemporarilyUnavailable { dependency: Dependency }

The portal controller authenticates an HTTP request and translates it into EligibilityRequest. The batch translator preserves row identity and translates each valid row into the same request. The support translator applies support permissions and invokes the same operation. None of those delivery details changes what eligibility means.

The application also states what facts it needs:

contract HouseholdFacts {
  load(subject: SubjectId, asOf: Date): Result<Household, FactsFailure>
}

contract IdentityEvidence {
  verify(subject: SubjectId): Result<VerifiedIdentity, IdentityFailure>
}

One adapter can call the legacy household provider. Another can call the replacement. A local test can return representative facts without contacting either system. The application owns names such as Household, FactsFailure, and asOf; the translator owns OAuth scopes, JSON fields, retry headers, and vendor error codes.

Replacement is not always transparent. If the old provider returns complete household records and the new provider returns partial, confidence-scored observations, the application has learned something important. The driven port may need to represent completeness or confidence. Hiding unknown as no would preserve the method signature while corrupting the decision.

This boundary depends on the same ownership question discussed in SOLID's Dependency Inversion Principle: policy should describe what it needs instead of importing a lower-level detail. Hexagonal Architecture applies that direction specifically to the application's interactions with outside actors.

What does it buy?

Business behavior can run through a portal, batch process, support tool, or automated test without being rewritten for each delivery mechanism. Policy tests can run without provider credentials or shared sandboxes. A provider migration can concentrate authentication, serialization, and error translation in one place.

Failures also become easier to locate. A typed TemporarilyUnavailable result is observably different from an ineligibility decision. An incident involving provider authentication can begin in the driven adapter instead of forcing responders to inspect the rule engine and every delivery path.

These mechanisms can return time to building when the outside systems are genuinely volatile or slow to coordinate with. They do not create that time merely because interfaces were added.

What does it cost?

Every port is a contract that must be named, maintained, and tested. Every adapter must translate data and failure meaning. Transaction ownership becomes explicit when one operation crosses storage and external services. A broad, generic port can hide useful capabilities; a narrow port per class can scatter the application into ceremony.

Mock-only tests create false confidence. A fake provider can satisfy the method signature while the real implementation sends the wrong JSON, mishandles authentication renewal, retries unsafe operations, ignores rate limits, or translates a vendor outage into a business rejection.

The boundary moves integration complexity outward. It does not make that complexity disappear. Driven adapters require contract or integration evidence for serialization, authentication, timeouts, retries, failure translation, idempotency, and the provider behavior on which the application relies. Driving adapters need tests for authorization, validation, row identity, and partial failure.

When is it worth using?

For an MVP, a well-named provider module and one shared application function may be the smallest reversible design. Direct calls are reasonable when learning speed dominates and the integration is unlikely to outlive the experiment.

For a growing product, introduce a port when a second driver appears, provider changes repeatedly disturb policy code, shared sandboxes block routine work, or integration failures are difficult to isolate.

For a mature platform, explicit contracts, multiple adapters, integration suites, failure semantics, and ownership for retries and transactions may be justified because many workflows depend on the boundary.

A short script, a single-purpose data import, or a stable utility with one integration may become harder to understand if every file operation receives a port. Apply the pattern around expensive conversations, not around every instance of input and output.

How do you know it is helping?

Compare the work before and after introducing one boundary:

  • Can policy tests run without credentials or a shared sandbox?
  • How long does the focused test suite take to start and finish?
  • How many policy files change during a provider migration?
  • Can responders identify whether an incident belongs to delivery, policy, or a provider translator?
  • Which defects are caught only by real integration tests?
  • Does the application contract express its own needs, or merely rename the vendor SDK?

A qualified local claim might be: “the team replaced the household provider without changing eligibility policy, and provider contract tests caught two serialization differences.” Netflix's production account of adopting Hexagonal Architecture is useful as a case report about preparing one system for changing services and data sources; it is not evidence that every application needs the pattern.

AWS's prescriptive guidance for the hexagonal pattern likewise describes applicability, benefits, and added complexity. The decision remains local to the volatility and test constraints of a particular boundary.

When should you simplify it?

Inline or remove a port when it has one stable implementation, its contract merely mirrors a vendor SDK, and translation creates more defects or navigation cost than it contains. Keep the integration tests if they protect real external behavior even when the internal abstraction becomes smaller.

Change the port when new provider semantics change what the application must know. Preserving an obsolete contract by discarding meaning is not decoupling; it is hiding information.

Sources