Lesson 0009 · Core Designer · Module 2

Controlling Dependency Direction

The most important arrows in your architecture point at the domain. Ports & Adapters is the mechanism for drawing them correctly — this lesson is the drawing lesson.

Reading ≈ 11 minPractice ≈ 25 min

Mission tie-in: dependency direction is what makes the domain your asset. Every later phase builds on this: repositories, infrastructure isolation, event-driven systems.

Knowledge: the arrow points inward

In a well-directed system, the domain — the rules that are true regardless of technology — depends on nothing. The world (databases, APIs, files, clocks) depends on the domain. The domain declares ports: the interfaces it needs. The world supplies adapters: implementations of those ports.

# the domain defines the port it needs:
class PaymentGateway(Protocol):
    def charge(self, amount: Money, token: str) -> str: ...

class CheckoutService:
    def __init__(self, gateway: PaymentGateway, orders: OrderRepository) -> None:
        self._gateway = gateway
        self._orders = orders

    def checkout(self, cart: Cart, token: str) -> Order:
        charge_id = self._gateway.charge(cart.total, token)
        order = Order.from_cart(cart, charge_id)
        self._orders.save(order)
        return order

Now the adapter, living outside the domain:

# infrastructure provides the adapter:
class StripeAdapter:
    def __init__(self, client: StripeSDK) -> None:
        self._client = client

    def charge(self, amount: Money, token: str) -> str:
        return self._client.payment_intents.create(...).id

Who owns the interface? The domain does. That single fact is the whole pattern. If the payment SDK defines what your checkout logic looks like, the arrow points the wrong way.

Test it: swap Stripe for a fake adapter and run checkout with no network, no SDK, no mocks — the domain never knows. The port made that possible.

How a senior designer audits an existing hexagon

A team whose README says "hexagonal architecture" and whose codebase has fourteen ports.

The first thing they check is not the arrows but the implementations. For each port: how many classes implement it, counting the test fake? A port with two or more is doing work. A port with exactly one implementation and no fake is unpaid indirection — it obeys the letter of the pattern and buys nothing, and there are usually four or five of them.

The question they ask per port: name the thing on the other side you might have to replace, or the test that needs the seam. If neither answer exists, the port exists because the pattern was applied, not because a problem was solved. Deleting it is a legitimate outcome of an architecture review, and saying so is what stops a good idea from becoming a ritual.

Then the interesting case. One port is ReportRepository, and its single method is:

class ReportRepository(Protocol):
    def run(self, sql: str) -> list[dict]: ...

Every dependency arrow points the right way. The domain imports no database driver. And the boundary is gone anyway, because the database's language crossed it inside a string: the domain is now writing SQL, and swapping the adapter would require rewriting every caller. This is the case worth memorising — you can satisfy the import graph and still lose the boundary, because ports are judged by vocabulary, not by the shape of the imports.

The alternative they reject. The obvious repair is to add a method to the port for each report: top_customers(), refunds_by_week(), and so on. Follow that and in a year the port has forty methods, every one of which is a query with a name — the ORM, reimplemented, with a worse query planner and no composability. The tell: the interface grows one method per use case and never stabilises.

The call they make instead is to stop pretending reporting is domain logic. Reads that answer questions — dashboards, exports, analytics — are given their own module that talks to the database directly and returns plain rows, while the port stays for the transactional domain where invariants actually live. This is not a compromise of the pattern; it is the recognition that the pattern protects rules, and a report has none.

The consequence, measured. While every new report went through the domain port, it needed a change to the interface, a change to the adapter, and a review from the domain owner: median lead time nine days for something an analyst could describe in a sentence. After the read path was split out, the same work was one module and one reviewer, and shipped the same week. The ports that remained got taken seriously again, because they were no longer in the way of work they had nothing to do with.

When this is the wrong move

Do not build a hexagon around a service whose domain is its schema. If the business rules amount to "validate these fields and store the row", the ports are ceremony and the composition root is a second thing to maintain; a straightforward layered service is honest and cheaper. Do not build a port for something you cannot actually replace — your language runtime, your cloud provider's identity model, the framework your whole company standardised on. The insurance premium is real and the claim will never be filed. And do not force read-heavy paths through a domain port: hiding a query language costs more than it protects when there are no invariants on the other side. Rules go through the port; reports go around it.

Skill: which way is the arrow?

Practice on your own code

Pick one external thing your code touches (a database, an API, a filesystem). Draw the arrow: does your domain's shape follow the external thing, or does the external thing conform to your domain? If the former, introduce a port — even if only for that one dependency. Then run the audit in the other direction: for every interface you already call a port, name the second implementation or the test that needs it. Any port that fails that question is a candidate for deletion, and deleting it is as much a win as adding one.

In the lab: the returns-resolution service imports a carrier client and a payments client directly inside its decision logic. The phase-1 checkpoint asks you to introduce one port shaped by what the decision actually needs — not by what the vendor offers — and to prove it by running the resolution rules in a test with no network and no mocking library.

Read and watch deeper

• "Hexagonal Architecture", Alistair Cockburn — the original statement of ports and adapters.
• Architecture Patterns with Python, Percival & Gregory — ch. 2 "Repository Pattern" and ch. 3, "A Brief Interlude: On Coupling and Abstractions": the Python working version of this lesson, including the fake repository that proves the seam.
• Clean Architecture, Martin — ch. 17–18 on drawing boundaries and their anatomy, and ch. 22, where the dependency rule is stated in its strongest form.
• import-linter — the tool that turns this lesson's arrow into a build failure. A rule your CI enforces outlives the review that agreed on it (lesson 0022).
• Watch: ArjanCodes YouTube — search "ports and adapters" or "hexagonal architecture".
• Reference: Glossary — port, adapter, dependency direction.

Map your project's dependency arrows with your agent-teacher — let it push back on where you claim the boundary is.