hexagonal-architecture

Hexagonal Architecture

A reference for Alistair Cockburn's hexagonal architecture — also called ports and adapters — read pragmatically. The hexagon isolates a domain core from the technologies that drive it (controllers, CLIs, jobs) and the technologies it drives (databases, HTTP APIs, mailers, object storage). Everything outside the core enters or exits through a port: an interface owned by the domain, implemented by an adapter owned by the infrastructure layer.

The pragmatic reading — most visible in Rails, but applicable wherever an Active Record-style ORM is idiomatic — treats the database as an integral part of the domain model. Active Record classes carrying domain behavior live inside the hexagon; no repository abstraction is imposed over them merely to satisfy hex purity. Ports are still essential, but only for seams that genuinely vary: third-party HTTP APIs, payment gateways, mailers, file/object storage, message brokers, SMS providers, and similar replaceable integrations.

Hexagonal architecture is not a universal requirement. It has a real cost in up-front plumbing and a learning curve for teams raised on Rails-style controllers-plus-models. It pays off when the application has several external integrations that change independently, when test costs at real boundaries are high, or when the team needs to swap infrastructure (mailer vendor, storage backend, payment provider) without touching business rules.

This document defines the six concepts below, each with the same structure:

• Intent — what the concept establishes, in one or two sentences.
• Signals — concrete things to look for in code, covering both misuse (the concept is applied wrong) and absence (the concept is missing where it would help).
• Not a violation when — conditions under which the apparent signal is benign.
• Remediation sketch — what a good application of the concept looks like.
• Interactions — how the concept reinforces or depends on neighbors.

Ruby/Rails idioms appear inline as illustrative examples. The concepts themselves are language-agnostic; the Ruby notes sharpen detection in the ecosystem this reference is most often used against.

Terminology

Pinned terms — used consistently throughout this reference and in the paired review skill:

• Domain core — the framework-independent center of the hexagon; the code that expresses business rules.
• Driving port — an interface representing a use case the application offers to the outside world (synonymous with inbound / primary / use-case port in other sources).
• Driving adapter — code that translates an external trigger (HTTP request, CLI invocation, queued job, webhook) into a call on a driving port.
• Driven port — an interface the domain core depends on to reach the outside world (synonymous with outbound / secondary / gateway port).
• Driven adapter — concrete implementation of a driven port against a specific technology (HTTP client, SDK wrapper, mailer, S3 client).
• Application Service — the orchestrator that implements a driving port; coordinates domain objects and driven ports to fulfill a use case (synonymous with Use Case / Interactor). Distinct from Domain Service.
• Domain Service — a stateless domain operation that doesn't belong on any single entity or value object, named in the ubiquitous language. See tactical-patterns §5.
• Composition root — the single place where adapters are wired to ports and injected into Application Services (a Rails initializer, a DI container, a factory module).
• Pragmatic boundary — the judgment about whether a seam in the code actually deserves a port, given the cost/benefit of the indirection.

Contents

1. Domain core
2. Driving side
3. Driven side
4. Application Service vs. Domain Service
5. Dependency direction and composition root
6. Pragmatic boundaries
7. Applying these patterns

---

1. Domain core

Intent. The domain core holds the business rules and is framework-independent. It does not know that HTTP exists, that jobs are processed by Sidekiq, that email goes through SendGrid, or that logs go to Datadog. Its only allowed collaborators are other domain objects and driven ports (as interfaces). The core changes when the business changes, not when the infrastructure changes.

Signals.

• Misuse — framework imports in the core. require "sidekiq", require "net/http", require "aws-sdk-s3", HTTParty, Faraday, ActionMailer::Base, or Rails.logger inside a domain file. The core has reached outside the hexagon directly.
• Misuse — web/transport concepts inside the core. Domain methods that take params hashes, ActionController::Parameters, request, response, or return rendered strings / JSON-shaped hashes. HTTP has leaked in.
• Misuse — job framework concepts in the core. Domain classes extending Sidekiq::Worker / ApplicationJob / ActiveJob::Base, or calling perform_async / deliver_later inline. The core has absorbed the transport.
• Misuse — transport objects threaded through domain methods. A domain method accepts an ActionDispatch::Request, a params hash, or a session, and reads transport-shaped attributes from it (request.remote_ip, request.user_agent, params[:foo]). The signature binds every call site to having a live HTTP request on hand. Common shape: SecurityEvent.record_event(event_type, request, ...), MagicLink#consume!(request:). Distinct from the params misuse above because the object is passed through, not just named — it is a persistent coupling, not a one-line ergonomic shortcut.
• Absence — no identifiable core at all. Business rules live entirely in controllers, jobs, and concerns; there is no file whose purpose is to express a domain rule independent of how it is triggered.
• Absence — Ruby: "service objects" as the whole core. app/services/*_service.rb files each instantiate HTTP clients, mailers, and AR models directly. There is no separation between business rule and integration.

Not a violation when. Active Record models carrying real domain behavior live in the core by design under the pragmatic stance — they are the domain objects. The inheritance from ApplicationRecord does not count as framework leakage for the purposes of this review. What is still forbidden: HTTP, job scheduling, external SDKs, mailers, and logging inside those AR classes.

Remediation sketch. Push framework-bound code out of the domain file. Replace a direct Net::HTTP.get(uri) with a call on an injected driven port (see §3). Replace an inline OrderMailer.confirmation(order).deliver_later with notifier.order_confirmed(order) where notifier is a driven port wired by the composition root. Move perform_async calls from inside domain methods up into the driving adapter that triggered them, or behind an explicit JobScheduler driven port if the act of scheduling is itself a domain decision.

Interactions. The domain core's integrity is what makes driven ports (§3) meaningful — the hexagon is defined by the boundary between core and ports. Cross-references from the core to driven ports are fine (the core owns them); cross-references from the core to adapter implementations are the canonical dependency-direction violation (see §5).

---

2. Driving side

Intent. Driving adapters translate external triggers — HTTP requests, CLI commands, queued-job invocations, webhooks, scheduler ticks — into calls on driving ports. A driving port is a small interface representing one use case the application offers ("confirm an order", "publish a post", "run the nightly billing job"). The driving adapter is thin: parse input, call the driving port, format the response. The logic lives on the other side of the port.

Signals.

• Misuse — fat driving adapter. A controller action that validates, looks up records, runs business rules, triggers side effects, and renders — several screens of code before a redirect. The use case has been implemented inside the adapter.
• Misuse — job as the use case. A Sidekiq worker whose perform method is the business logic, not a thin dispatcher to an Application Service. When the same logic needs to run synchronously (from a controller), it gets duplicated or the worker is called inline awkwardly.
• Misuse — driving port shaped like HTTP. A driving port whose method takes a params hash, an HTTP verb, or returns a rendered response. The port has absorbed the transport instead of abstracting it.
• Misuse — CLI / Rake task as the use case. A rake billing:run_monthly whose body is 80 lines of orchestration. Same problem as the fat worker: the task is the adapter, not the use case.
• Absence — no driving ports, only controllers. Every external trigger type (controller, job, CLI) re-implements the use case from scratch. Running the same operation from two entry points duplicates logic or forces one entry point to call the other awkwardly (e.g., a job that fakes an HTTP request, or a rake task that instantiates a controller).
• Misuse — deprecated-but-retained parallel implementations. A use case kept alongside a newer job-graph implementation, with a docstring like "retained for backwards compatibility / synchronous tests". Two places now describe "what it means to run this operation", and they drift. In hex terms, the driving adapter (job) has absorbed the use-case logic rather than calling into it — the old use case becomes a ghost. Either collapse the job into a one-line wrapper around the use case, or delete the use case. The middle state is a drift risk.
• Absence — Ruby: controllers calling Model.where(...), Model.find(...), and AR mutators directly. Signals that the use case is being composed inside the driving adapter.

Not a violation when. A controller action that is genuinely a thin read — render json: Post.find(params[:id]) — does not need a driving port. The pattern pays off when the use case is a meaningful verb (confirm, publish, settle, refund, cancel), not for thin CRUD passthroughs.

Remediation sketch. Extract the use case into an Application Service (see §4) behind a driving port. The controller action parses params, constructs the inputs, calls application_service.call(...), and renders the result. The same Application Service is callable from a Sidekiq worker, a Rake task, or a test, all without re-implementing orchestration. In Rails this often looks like PostsController#create calling Posts::Publish.new(...).call(input), where Posts::Publish is the driving port's single implementation.

Interactions. Driving adapters are the mirror of driven adapters (§3); both sit outside the hexagon and depend on ports. A thin driving adapter is only possible when Application Services (§4) exist to implement the driving port.

---

3. Driven side

Intent. Driven ports are interfaces the domain core depends on to reach the outside world — everything it cannot do alone. Driven adapters implement these interfaces against specific technologies. The core receives a notifier, a payment_gateway, a file_store, a clock, an idempotency_store — named for what they are in the domain, not for the technology behind them. Swapping SendGrid for Postmark, S3 for GCS, or Stripe for Adyen is an adapter change; the core doesn't notice.

Signals.

• Misuse — driven port named after its adapter. SendgridClient, S3Client, StripeGateway exposed to the domain by those names. The adapter's identity has leaked into the port. Ports should be named for the domain role (Notifier, FileStore, PaymentGateway) with adapter classes like SendgridNotifier, S3FileStore, StripePaymentGateway implementing them.
• Misuse — port that's just a pass-through. A driven port whose methods map one-to-one onto a vendor SDK's methods with no translation to the domain's vocabulary. The port is not really abstracting anything; it's a renaming layer.
• Misuse — leaky return types. A driven port that returns Faraday::Response, Stripe::Charge, Aws::S3::Object, or raw vendor exceptions. The adapter's data shapes flow into the core.
• Misuse — chooser inside the adapter. The adapter class internally branches on configuration to dispatch to a second implementation (usually a simulator, fake, or "dev mode" stand-in). VertexAiService.generate_content that checks GoogleCloud.configured? and delegates to VertexAiSimulator is the canonical shape. The implementation-selection decision is exactly what a composition root should make — the adapter should be the real implementation only; the simulator should be a sibling adapter chosen at wiring time. Also couples the production adapter to its own test double.
• Absence — direct instantiation in the core. Net::HTTP.get(URI(...)), HTTParty.post(...), Stripe::Charge.create(...), Aws::S3::Client.new.get_object(...), OrderMailer.confirmation(order).deliver_later, Twilio::REST::Client.new.messages.create(...) in a domain file. The core has skipped the port and reached straight for the technology.
• Absence — Time.now / Time.current in domain logic that needs to be testable. The clock is a driven concern; pervasive direct calls make time-dependent rules awkward to test and impossible to shift for scenarios like backfills.
• Absence — hard-coded external IDs or URLs in the core. Endpoints, vendor identifiers, and credentials read directly from ENV or Rails credentials inside domain code. The core is negotiating with the outside world on its own.

Not a violation when. The dependency is on the idiomatic ORM (see §6). Under the pragmatic stance, the Active Record query interface is part of the domain's working vocabulary; imposing a Repository over it to satisfy hex purity is ceremony without payoff. The rule re-engages the moment the dependency is on an external system the ORM cannot mediate.

Remediation sketch. Define the port as an interface in the core, named for the domain role: Notifier#order_confirmed(order), PaymentGateway#charge(amount:, customer:), FileStore#put(key:, body:). Implement it in an adapter class in app/adapters/ (or equivalent). Inject the adapter through the Application Service's constructor; wire it in the composition root. The port's method names are domain-speak; the adapter translates them into whatever the vendor SDK wants. Return domain values or raise domain exceptions — never vendor types.

Interactions. Driven ports are the hexagon's contract with the outside world; their integrity is what keeps the domain core (§1) stable under infrastructure change. Driven ports are distinct from tactical-patterns Repositories — under the pragmatic stance, the ORM plays the Repository role and does not sit behind a driven port. Driven port tests benefit from the supple-design properties described in supple-design — a port shaped around a side-effect-free query half and a commanding half is easier to fake.

---

4. Application Service vs. Domain Service

Intent. An Application Service is a use case: one public entry point, parameters flowing in, a result flowing out, and orchestration of domain objects and driven ports in between. It implements a driving port. A Domain Service is a stateless domain operation named in the ubiquitous language, usually spanning aggregates or computing something that doesn't sit naturally on any single entity. They solve different problems and belong at different layers.

Signals.

• Misuse — Application Service that's a pure pass-through. A one-line call method that delegates to a single AR method (Order.find(id).confirm!) with no orchestration, no coordination across aggregates, and no driven-port interaction. The service is ceremony around a method call; either inline it or the method deserves a real body.
• Misuse — Domain Service with infrastructure dependencies. A class named SomethingCalculator or SomethingPolicy that takes an HTTP client, a mailer, or an AR repository in its constructor. That's an Application Service mislabeled, or a driven-port consumer in disguise. Domain Services depend only on domain objects.
• Misuse — Application Service named like a Domain Service. TaxCalculator, PricingRules, EligibilityPolicy that happen to call driven ports and mutate records. The name is domain-shaped; the role is orchestration. Rename to a use case (QuoteTax, ApplyPricing, CheckEligibility) or collapse to a Domain Service and move the orchestration elsewhere.
• Misuse — god Application Service. A single CheckoutService#call that validates, prices, reserves inventory, charges, notifies, and writes audit. Split by meaningful use case; a use case is typically one transactional intent.
• Misuse — Ruby: ApplicationService base class with a single call convention, used for both roles indiscriminately. The base class signals that services are the primary carrier of behavior; it often hides the distinction between orchestration and domain computation.
• Misuse — adapter disguised as service. A class lives in app/services/, is named *Service, but its body calls a framework transport directly (Turbo::StreamsChannel.broadcast_*, ActionCable.server.broadcast, raw SDK methods) and/or renders views. That is a driven adapter wearing Application-Service clothing. Callers import a class whose name suggests domain reasoning but whose behavior is pure transport. Rename to *Broadcaster / *Adapter and move to app/adapters/, or extract a proper port when variance or test cost warrants it. The *Service suffix should be reserved for Domain Services and Application Services.
• Absence — no Application Service layer at all. Controllers call domain methods directly, so every new driving adapter re-implements orchestration. Driving ports (§2) become impossible to define cleanly.

Not a violation when. A single-line Application Service is justified when it exists to expose a domain method through a driving port — the ceremony is paying for the port, not for the line of code. Similarly, a Domain Service with no infrastructure dependencies but many inputs is still legitimate (TransferFunds.call(from:, to:, amount:) that coordinates two aggregates is the textbook case from tactical-patterns §5).

Remediation sketch. For each use case, define an Application Service with one public method, constructor-injected driven ports, and a clear return type. Keep Domain Services stateless and infrastructure-free; they receive domain objects and return domain values or raise domain errors. When a would-be Domain Service needs a driven port, that's the signal: promote it to an Application Service, or extract the domain calculation into a pure helper and keep the orchestration at the Application Service layer.

Interactions. Application Services implement driving ports (§2) and consume driven ports (§3). Domain Services live entirely inside the domain core (§1) and are described more fully in tactical-patterns §5. The Application Service / Domain Service split is the hexagonal counterpart of the driving port / driven port split: each axis separates orchestration from computation.

---

5. Dependency direction and composition root

Intent. The cardinal rule of hexagonal architecture: dependencies point inward. Adapters depend on ports. Ports are owned by the domain core. The core depends on nothing from the outside layer — it can compile, load, and run without knowing which adapters exist. The wiring happens at a composition root: one place, outside the core, where concrete adapters are instantiated and injected into Application Services.

Signals.

• Misuse — core imports adapter. A domain file requires or references SendgridNotifier, StripePaymentGateway, S3FileStore directly. The arrow points outward. Tests can't substitute a fake without monkey-patching.
• Misuse — core instantiates the adapter inline. notifier = SendgridNotifier.new inside a domain method. Equivalent to the previous signal; just more easily missed because there's no require.
• Misuse — port and adapter defined in the same file. Makes it hard to see the arrow and almost guarantees the core drags the adapter along. Split into two files: the port's interface lives in the core, the adapter lives in app/adapters/.
• Misuse — composition scattered across the core. Every Application Service builds its own adapters in its constructor, reading ENV and assembling HTTP clients. The composition root is implicit, which means there are several of them, inconsistent.
• Misuse — use case is its own composition root. The Application Service lazily news its adapters in private accessors (def s3_service; @s3_service ||= Aws::S3Service.new; end) or calls them statically (VertexAiService.generate_content(...)). Distinct from "no composition root at all": the codebase may have a perfectly good Application Service layer, but every use case assembles its own wiring. Tests must stub concrete classes globally; swapping an adapter means editing many files. Constructor-inject the ports with defaults pointing at a single composition root.
• Absence — no composition root. Adapters are new'd at the point of use. Wiring is ad hoc. Swapping an adapter for testing or for a new vendor requires editing every call site.
• Absence — Ruby: no Rails initializer or DI container wiring ports. No config/initializers/adapters.rb (or equivalent) where Rails.application.config.x.notifier = SendgridNotifier.new(...) happens; no dry-container / dry-auto_inject setup; no factory module returning configured Application Services.

Not a violation when. A pure-domain computation that depends only on domain objects has no adapters to wire and no composition-root concern. The rule is about the boundary, not about every class.

Remediation sketch. Establish one composition root. In a Rails app, that is typically a config/initializers/adapters.rb that reads configuration and builds adapter instances, exposing them via Rails.application.config.x.<role> or a small Dependencies module. Application Services accept their driven ports via the constructor: Posts::Publish.new(notifier:, clock:). Tests swap in fakes directly. In larger apps, dry-container / dry-auto_inject or a hand-rolled factory module formalizes the wiring, but the principle is unchanged: one place assembles, everywhere else receives.

Interactions. The dependency direction is what gives §1–§4 their meaning; without it, "driven port" is just a renamed variable. The composition root is where the pragmatic stance (§6) is made explicit: it's the file that decides which external dependencies get ports and which are consumed directly.

---

6. Pragmatic boundaries

Intent. Not every seam deserves a port. A port costs an interface, an adapter class, a constructor parameter, a line in the composition root, and a place in every test's setup. The pragmatic stance is explicit about when that cost is worth paying and when it isn't. In Rails, this means the ORM is part of the domain and does not get a port; external systems that vary do.

Signals.

• Misuse — port over the ORM. OrderRepository#find(id) → order = Order.find(id) implemented by an AR-backed adapter. The indirection adds nothing: the ORM is already the abstraction, and swapping it out is not a real scenario. Typical sign that someone has imported the hex rulebook literally without weighing the cost.
• Misuse — port over a framework primitive. A Logger driven port wrapping Rails.logger; a Cache port wrapping Rails.cache. These primitives are the abstraction; introducing a port over them is indirection for indirection's sake unless you genuinely plan to swap the framework.
• Misuse — port introduced for testing only. A driven port whose only adapter is the production one and whose only swap is a test double. When the port exists solely because tests find the concrete thing awkward, the smell is usually in the concrete thing, not in the absence of a port. Either improve the concrete API or accept an in-memory test double of the real type.
• Absence — no port around a replaceable external system. Direct calls to Stripe::Charge.create, Net::HTTP.post, Aws::S3::Client.new.put_object, Twilio::REST::Client.new.messages.create, Faraday.post inside the domain core. The seam is exactly what a driven port is for: external, variable, vendor-bound, and expensive to test.
• Absence — no port where vendor exceptions leak to the core. The core catches Stripe::CardError, Faraday::ConnectionFailed, Aws::S3::Errors::NoSuchKey. The vendor's failure taxonomy has become part of the domain vocabulary.

Not a violation when. The ORM is used in Rails idiomatically and there is no realistic plan to swap it. A scope chain in a query method on an AR model is not a hex violation under the pragmatic stance. A logger call on Rails.logger from a domain method is acceptable if the team has weighed and accepted that dependency.

Remediation sketch. Apply three criteria to every candidate external dependency:

1. Variance. Will this dependency plausibly be swapped — vendor change, dual-write during migration, multi-region rollout? If yes, port it.
2. Test cost. Does hitting the real thing in tests cost time, money, or determinism? If yes, port it so tests can substitute a fake.
3. Ownership boundary. Is this a system owned by a different team, vendor, or platform? Cross-ownership seams benefit from explicit contracts.

Two yeses → port. One yes → judgment call, often worth portfolio consistency (if you have ports for other vendors, add one). Zero yeses → no port; consume the thing directly and save the indirection for cases that need it. For the ORM in a Rails app, all three answers are typically no, which is why the pragmatic stance leaves it alone.

Interactions. The pragmatic stance is the corrective to naive hex: it explains why the dependency direction rule in §5 does not force every collaborator into a port. It relies on the composition root (§5) to make the decisions explicit: the root is where you see which collaborators crossed the threshold and which didn't. It intersects with tactical-patterns Repository (§6 there): a driven port for an external data source is a Repository in the DDD sense; the ORM-as-domain stance means the internal repository role is already played by the ORM.

---

Applying these patterns

• Dependency direction is the cardinal rule. Everything else in this reference is in service of it. When in doubt, check the direction of the arrows: core → port (allowed, core owns the port); adapter → port (allowed, adapter implements); core → adapter (never, the canonical violation).
• Name ports for the domain role, not the adapter. Notifier and PaymentGateway, not SendgridClient and StripeGateway. The point is that the core doesn't know which one is behind the port.
• Detect the pragmatic stance before scanning. A codebase under the ORM-as-domain stance will have AR classes in the core by design; this is not a violation. A codebase under the fully-separated stance will have POROs in the core and AR-backed repositories as adapters. Findings change shape between the two.
• Thin driving adapters, thin driven adapters. Both edges of the hexagon are places where logic accumulates if no one's watching. The work belongs on the inside.
• Application Service and Domain Service are different roles. See tactical-patterns §5 for the Domain Service pattern; the distinction is easy to muddle in a codebase that uses "service" as a catch-all suffix.
• Hex boundaries and Aggregate boundaries often align. An Application Service's transaction usually scopes to one aggregate (see tactical-patterns §3). When an Application Service modifies two aggregates, the hex structure isn't wrong — but domain events or an explicit cross-aggregate policy should be weighed.
• Ruby examples are illustrative. The concepts are language-agnostic. In non-Ruby codebases, translate the signals into the target language's idioms — the misuse and absence categories remain the same.