Why only one side has ports#

If ports are this useful, why doesn’t the inbound side have them?

Because nothing on that side needs inverting. A callee never needs to import its caller — you write a function without knowing in advance who will call it. The signature is the contract.

You only declare contracts for what you call outward.

Where application sits#

Application is inside the hexagon, wrapped around domain. And — this is easy to get wrong — it doesn’t connect to adapters, it connects to ports.

It looks like it touches adapters because the object in its hand at runtime really is an adapter instance. But all it knows is that it’s a StoragePort. Which one it actually is, only the composition root ever knew, and only for an instant.

Neither of the two arrows above changes when you add application — this layer doesn’t take part in the inversion, it just stands on top of where the inversion happens.

Which is also why run_pipeline is so easy to test: hand it a fake StoragePort. No patching required.

Folders attract things#

This boundary is not naming fastidiousness.

In that service, run_pipeline originally sat under domain/services/. Its dependency direction was clean — it imported only domain — so looking at that one file, moving it changes nothing.

But a feature was coming: on a hard failure, re-run with a stronger model. That logic is application’s. “What counts as failure” is a business rule; “what to do about it” is use-case policy.

If run_pipeline stays under domain/services/, the natural place for that new code is right next to it — which means inside domain.

A misplaced file is cosmetic. A misplaced folder keeps attracting the wrong things.

So the trigger isn’t “wait until it imports an adapter”. It’s when the second application-layer thing gets written. Move it while it’s still one file: one git mv and one import line.

domain holds four different kinds of thing#

domain/ is not a synonym for services. There are at least four kinds under it, and only one is a service:

1
domain/
2
├── models.py     entities and value objects
3
├── schema.py     output contract
4
├── ports.py      interfaces
5
└── services/     homeless rules

The test: a rule that clearly belongs to one entity should live on that entity, not become a service.

checksum_is_valid(code: str) -> bool is genuinely homeless — it’s a rule about a string; Order owning it is a stretch and Invoice is worse, so it became a service.

The counter-case: writing “is this document empty” as document_is_empty(doc) instead of a property on SourceDocument strips behaviour off the data. That’s an anemic model.

So application strings together more than services — it also strings together rules the models themselves carry. It sequences steps; where the rule inside a step lives is a separate question.

It isn’t a layer, it’s a moment#

Calling it a layer is inaccurate — it’s often a single file.

Layering is a static question: who may import whom, decidable from the source, fixed at compile time. The composition root is a dynamic question: at which moment the concrete type is spoken aloud.

It isn’t a layer. It’s a moment.

And the reason it must exist: dependency inversion cannot invert forever. Someone has to say the name eventually or nothing runs. The composition root is the one place allowed to say it, and the price is that it may say it only once, at the very start, before stepping off stage — after which only interfaces move through the system.

That’s the other face of the library test. A library can’t ship its own composition root precisely because when to choose an implementation belongs to whoever uses it, not to the library.

A Protocol guarantees shape, never behaviour#

Consider these two classes:

1
class NullResultSaver(ResultSaverPort):     # does nothing, on purpose
2
    def save(self, n, is_odd) -> None: pass
3

4
class BrokenFileSaver(ResultSaverPort):     # forgot to write the file — a bug
5
    def save(self, n, is_odd) -> None: pass

The code can be identical. Same shape, opposite intent. The type checker passes both; neither crashes at runtime.

A Protocol makes implementations substitutable, not correct. Only tests separate them — the null adapter’s test asserts the directory is still empty; the file adapter’s asserts those three lines appeared. Intent lives in assertions.

One more thing: a Protocol is zero-cost and zero-effect at runtime. Return something that doesn’t satisfy the port at all from the composition root, and Python doesn’t care at the moment of injection — it runs all the way to the domain call before raising AttributeError, two layers away from the cause. Protocols exist entirely for the static type checker and for whoever reads the code. If your CI doesn’t run mypy or pyright, they degrade into documentation.

Nothing enforces the dependency direction#

I rewrote the toy repo’s domain into the “dead port” shape — three edits:

1
from hex_lab.adapters import FileResultSaver              # ① domain imports the concrete class
2

3
def check_and_save(n: int, saver: FileResultSaver | None = None) -> bool:   # ② annotated concretely
4
    saver = saver or FileResultSaver("results.json")                        # ③ domain constructs it
5
    result = _is_odd(n)
6
    saver.save(n, result)
7
    return result

port.py, adapters.py, and bootstrap.py were untouched. Then three commands.

The program ran. Every test passed.

1
uv run --with mypy mypy src/
2
Success: no issues found in 7 source files

mypy was completely green.

Architectural violations are invisible to the type system. mypy checks “can A be used as B”. It never checks “should A know about B”. No type checker warns you when you point the dependency arrow backwards.

Tests didn’t catch it either — they all injected the saver explicitly, so none ever reached that default branch.

This boundary can only be held by people. Automating it means adding something like import-linter, which exists specifically to declare “this layer may not import that one”. That’s an extra tool, not something the type checker gives you free.

And the feel of the broken version is very concrete: ResultSaverPort drops to one reference — its own definition — and becomes dead code; bootstrap.py is called by nobody and is hollowed out; changing the default to “don’t persist” now means opening the pure business-logic file; and "results.json", a piece of infrastructure config, is hardcoded into the business layer.

A real comparison#

Back to the service I read. It defines two ports. Grepping the repo with the ruler above:

1
PortA  → 1 occurrence in the whole repo: its own definition. Zero references.
2
PortB  → 5 occurrences: type annotations across three files, plus injection.

PortA is dead code. Two domain services import the concrete adapter class directly, annotate parameters with the concrete type, and construct a default inside the function body — matching the broken version from the last section symptom for symptom.

PortB has three implementations: one production, two test doubles.

The difference isn’t design skill. It’s whether testing forced a second implementation into existence.

Behind PortA is a PDF parsing library. Nobody needs to swap it and tests can use real files, so a second implementation was never built, and the inversion decayed back to the default state.

Why LLM calls are the best case for a port#

If you build AI-adjacent systems, this pattern pays off more for you than for most people, for three reasons specific to the setting:

First, the dependency really does change, and often. Provider, access path (direct API vs a cloud vendor’s hosting vs an internal gateway), model ID — something moves every few months. Compare a PDF library, which you won’t replace in three years.

Second, testing forces a second implementation on you. Real LLM calls are slow (seconds), cost money, and are non-deterministic. No test that has to run fast can hit the real API. Note the causality — it isn’t “we designed well, so we have two implementations”, it’s “tests can’t use the real call, so the second implementation was forced into existence”.

Third, you need pinned output to test what comes after. Downstream of the LLM sits a long stretch of deterministic logic: parsing, schema validation, assembly, repairing malformed JSON. All of it is testable, but only if you can inject a fixed response. The port is that injection point.

One trap worth calling out: it’s easy to shape the port like one specific provider. If concepts only one vendor has show up in your port’s signature — a particular content-block structure, a vendor-specific parameter name — it isn’t a port, it’s a wrapper. Domain still has to change when you swap providers.

The self-check is simple: hand this port’s signature to a different provider to implement. Does the signature need to change? If yes, the abstraction leaks.

And one boundary to settle early: which side of the port do retry, backoff, and rate limiting live on? Inside domain, you rewrite them for every provider. In the adapter or the gateway, domain never learns retries exist. Decide it sooner rather than later.