What are the concrete costs of adopting Hexagonal Architecture for a service, and what characteristics of a project should make a team hesitate before applying it?

## Where the costs land Every architectural pattern trades one kind of cost for another kind of benefit, and Hexagonal Architecture's costs are concentrated in three places. 1. **The first is raw volume.** Each port requires at minimum an interface definition, and — because a port with zero implementations is dead code — at least one adapter implementing or calling it; for a service with, say, eight distinct external dependencies (three datastores, two third-party APIs, an email sender, a message queue, a cache), that's eight extra interface files plus eight adapter classes beyond whatever the core itself needs, before counting driving-side ports for however many entry points exist. For a small team or a small service, this can genuinely double the file count for functionality a straight, framework-coupled implementation would deliver in half the code. 2. **Second is navigability cost.** Reading a call chain in hexagonal code means following controller to driving-port interface to core implementation to driven-port interface to adapter, and an IDE's "go to definition" on the port often lands you on the interface, requiring an extra "find implementations" step to reach the actual adapter code — a minor friction per hop that compounds when onboarding someone unfamiliar with the codebase. 3. **Third is composition-root cost.** The code that wires concrete adapters to ports is itself a nontrivial artifact that grows with the number of ports, and misconfiguration there — a wrong adapter bound to a port, a missing binding causing a startup failure, or a wrong binding that doesn't fail startup, as in the earlier example of a test fake wired into production — is a class of bug unique to this style of design. ## When the costs are worth paying These costs are worth paying, and are standard advice for, systems with meaningful business-rule complexity — logic with many conditional branches, invariants, and edge cases that benefits from being tested in isolation, repeatedly, without infrastructure noise — and/or systems with a credible, not hypothetical, need for multiple adapters: a payments core that genuinely will be exposed via both a synchronous API and an event-driven consumer, or a system that must support two different infrastructure providers' native storage for regulatory or multi-tenant reasons. The return on the extra indirection is concentrated exactly where change and testing pressure are highest. ## When to hesitate The costs are NOT worth paying, and teams should hesitate, in a few recognizable situations. - **A thin CRUD service** — expose a database table's fields through an API with light validation and no meaningful business rule beyond field-level checks — gets essentially zero benefit from ports, because there's no complex logic worth isolating and, in practice, the database is almost never actually swapped out; the interfaces just add a layer of indirection between the controller and the persistence call that was already going to happen. - **Early-stage or prototype work**, where the domain model and its rules are still being discovered and are expected to be rewritten multiple times in the first few months, is another poor fit: drawing and redrawing correct port boundaries is itself expensive, and volatile requirements mean the "stable core, swappable edges" assumption the pattern is built on doesn't hold yet — teams in this phase often do better prototyping with a simpler layered or even transaction-script style and introducing ports later, once the domain has stabilized enough that the boundary is worth committing to. - **A third situation is a genuinely tiny, single-purpose service**, such as an internal cron job that reads one table and writes one file, where there's realistically never going to be a second adapter on either side and the operational lifetime of the service is short. ## Selective adoption, and its own risk A useful heuristic in practice, used by several teams doing pragmatic hexagonal adoption, is to apply the pattern selectively within a codebase rather than uniformly: - put real port/adapter discipline around the modules with genuine business complexity or a credible multi-adapter future (e.g., a pricing engine, a fraud-check module); - let simpler CRUD-shaped modules (e.g., managing user notification preferences) stay as a thinner, more direct layered implementation, accepting the inconsistency in exchange for not over-engineering the simple parts. The risk of this selective approach is **architectural drift** — the boundary between "deserves ports" and "doesn't" is a judgment call that can be argued about and can shift as a module's complexity grows, so it needs an explicit, revisited decision rather than being left as an accident of whoever wrote the module first.