hex-architecture

Use when the family is already settled as hexagonal and the question is where a module belongs or whether an import may cross a boundary — the four layers, inward-only dependencies, ports, adapters, t

SKILL.md

GitHub

Hexagonal Architecture — the layer contract

Which layer a thing belongs to, and what it is allowed to reach. This skill owns boundaries only: the mechanics of packaging a module and spelling an import are python-packaging, and they are the same here as in any other project. What goes inside a module belongs to whichever skill owns that artifact.

When to use vs. neighbours

  • Whether this style is the right one at all, or the service belongs in the flat-layered family → architecture-choice, which owns the hex-vs-flat decision in full and is universal, so it is available whichever family plugins are installed.
  • The family is settled the other way — a worker, crawler, pipeline or integration service grouped by technical role, with no ports until a second real implementation → flat-layered, in the pyhouse-flat plugin. Nothing in this skill applies there.
  • Where a boundary goes at all — split vs merge, whether an integration needs a contract, how much structure a component deserves → coupling, loaded alongside this skill; it owns the boundary reasoning, this skill owns the layer layout.
  • Deciding where a module belongs, or whether an import may cross a boundary → this skill.
  • Moving code between layers, or restructuring a layer package's public surface → this skill for where it lands; python-packaging for how the module and its re-exports are spelled.
  • Editing the body of an existing module, once its layer is settled → that artifact's skill (hex-domain-model, hex-domain-ports, hex-domain-service, hex-application, hex-persistence, hex-restapi-endpoint, …). Each already assumes the boundaries this skill sets.
  • One class per module, __all__, the __init__.py contract, relative vs absolute → python-packaging.
  • Choosing an annotation form or a collection type → python-style; the level and fields of a log event → python-logging; which layer logs is below.
  • The error catalog → exception-catalog.
  • What a queue consumer or a webhook route owes the unit delivered to it, and what a relay owes the effect it sends → at-least-once-delivery; where the entrypoint does it is below.
  • Deriving a concrete path or class name from an identifier → hex-conventions.
  • Library substrate and the migration bootstrap → hex-project-setup; toolchain config → python-toolchain.
  • A table, a relational repository, a migration → hex-persistence.
  • Compensation → hex-application; a unit of work → hex-persistence.
  • What the composition root actually binds — providers, lifetimes, settings, teardown, declaration order → hex-wiring. This skill owns only that the root exists — one module, src/myapp/containers.py — and that nothing else imports a concrete adapter.
  • Turning the import rules below into an automated test → test-architecture-rule.

The four layers

Three are core — domain/, application/, infrastructure/; the fourth is one or more entrypoint packages (restapi/, cli/, worker/). The split exists so the business rules in domain/ stay independent of databases, HTTP frameworks and SDKs, and so the dependency graph stays acyclic.

                    ┌──────────────────┐
                    │  entrypoints     │   restapi/, cli/, worker/
                    │                  │   build containers.py, translate
                    │                  │   transport ↔ application
                    └────────┬─────────┘
                             │ may import all three core layers
                             ▼
        ┌────────────────────────────────────────┐
        │            application/                │   commands, queries,
        │   (orchestration, no business logic)   │   handlers (CQRS)
        └────────────┬───────────────────────────┘
                     │ imports domain only
                     ▼
        ┌────────────────────────────────────────┐
        │              domain/                   │   entities, VOs, enums,
        │   (pure logic, stdlib only)            │   protocols, exceptions,
        │                                        │   services
        └────────────▲───────────────────────────┘
                     │ implements protocols
                     │
        ┌────────────┴───────────────────────────┐
        │           infrastructure/              │   adapters, repositories,
        │   (third-party SDKs, IO)               │   tables, clients
        └────────────────────────────────────────┘

Dependency direction: application → domain ← infrastructure, and entrypoints → all three. No other arrow is legal.

What each layer may import

domain/

  • Allowed: stdlib (dataclasses, datetime, enum, uuid, typing), other domain modules.
  • Forbidden: everything else. No third-party libraries — no ORM, no settings library, no HTTP client, no cloud SDK, no web framework. No application/, no infrastructure/, no entrypoint imports.
  • Defines: entities, value objects, enums, filter records, domain protocols (I* / ICan*), domain services, domain exceptions, type aliases. In a hexagonal service the project's one exception catalogue (exception-catalog) lives in domain/exceptions.py.
  • Zero IO. No file reads, no network, no database, no logging.

application/

  • Allowed: stdlib, the logging library, domain modules. The logging carve-out exists for one reason: this is the layer that logs business successes (the layer table under Who logs, by layer allocates it), so it carries the logging facade and nothing else outward. A second third-party import is not covered by it.
  • Forbidden: third-party libraries beyond logging. No infrastructure/ imports, no entrypoint imports.
  • Defines: commands, queries, handlers, result DTOs.
  • Depends on infrastructure capabilities only through domain protocols, and receives concrete adapters by injection.

infrastructure/

  • Allowed: stdlib, any third-party library, domain modules for protocol types and entities.
  • Forbidden: application/ imports, entrypoint imports.
  • Defines: adapters implementing domain protocols — relational repositories, object storage, token verifiers, renderers.
  • Translates between external representations (database rows, HTTP JSON, queue messages) and domain objects. Translation happens inside the adapter; a raw row or SDK object never leaks upward.

Entrypoint packages — one package per entrypoint kind, named for the kind, so that dropping or adding a transport moves one directory. The catalogue spells the HTTP one restapi/; api/, web/ and http/ are equally good words and nothing depends on which, but two transports sharing a package is a defect. Siblings are cli/ and worker/; a command's own rules are python-cli's.

  • Allowed: everything. An entrypoint builds the composition root, src/myapp/containers.py, at startup, runs its settings check (hex-wiring rule 2) before it serves or takes work, and closes it at shutdown; the root itself is that one module, not the entrypoint package.
  • Defines: HTTP routes, CLI commands or queue consumers; request and response wire schemas; the central error handler; the dependency wiring.
  • Wires containers.py at startup, resolves handlers, translates transport ↔ application DTOs.
  • Opens one per-operation scope per request, message or call, and closes it when the operation ends.
  • Has one scope that catches what propagates, logs it once and turns it into that transport's outcome — a status, an exit code, the unit returned or rejected (at-least-once-delivery rules 1 and 2) — mapped from its class here and never stored on it in domain/, with any body read off the exception's own attributes (exception-catalog rules 6 and 13).
  • Acknowledges a message only after its handler returns, and returns it when the handler raises. A create it drives carries the identity the message supplies (hex-application, command handler rule 6), so a redelivery finds what the first delivery wrote. A redelivered create that meets the record its first delivery wrote, under the same identity, is acknowledged as done, never mapped to a conflict or a dead letter (at-least-once-delivery rule 3): a create a delivered unit drives is written to resolve a conflict on its own identity as nothing to do (persistence rule 15), the statement being hex-persistence's, so no conflict reaches the scope. The rest of what a delivered unit is owed — bounded redelivery to a dead letter, a redelivery that changes nothing, a sender's signature — is at-least-once-delivery's.

Who logs, by layer

python-logging's rule — an error is logged once, by the scope that stops it — lands here as a layer table: every error propagates to one central handler, so the scope that does not re-raise is the entrypoint.

Layer May log
domain/ Nothing. Zero IO includes the log socket; raise an exception carrying context instead.
infrastructure/ Nothing. An adapter translates and re-raises, so it is never the layer that stops; the low-level detail goes into the translated exception's context, where the layer that does log will find it.
application/ Successes only, at info, after the operation completes. Never errors — they propagate. Two exceptions, each a failure the handler stops rather than re-raises: a failed undo under best-effort compensation, logged at warning (python-logging, "A failed undo under compensation"), and a failed side effect of a command already committed, logged once after the success event (hex-application, After the store write).
entrypoints Errors, once, at the central handler, with request context attached.

A central handler takes python-logging's level guide, plus one case only it sees: an exception that is not a catalogue class → error, logged by the entrypoint's own catch-all, which answers it without handing it back to the framework or server, whose last-resort handler would log it a second time. The call that implements it is error_handler.py in hex-restapi-app.

Top-level layout

src/myapp/
├── containers.py         # dependency wiring (the composition root)
├── domain/               # pure business model
├── application/          # CQRS orchestration
├── infrastructure/       # adapters
└── restapi/              # HTTP entrypoint

domain/ and application/ mirror the same subdomain partition — domain/foos/, application/foos/. infrastructure/ groups by external technology, not by subdomain: infrastructure/postgres/, infrastructure/redis/, infrastructure/s3/, infrastructure/jwt/ (the derivation is hex-conventions). A new subdomain adds a folder under domain/ and application/; a new external technology adds one under infrastructure/.

Packaging and imports — not owned here

One class per module, __all__ placement, the __init__.py wildcard re-export contract, relative vs absolute imports, the collapsed same-package form and import ordering are architecture-neutral and live in python-packaging. They apply here unchanged; this skill adds only what the layer split imposes on top of them:

  • The distribution root's __init__.py stays empty — python-packaging's carve-out for an application's root, with a layered reason: aggregating the layer subpackages to the root would make import <package> transitively pull infrastructure and entrypoint third-party dependencies on every use, and would destroy the dependency-free domain / application import path.
  • A layer package re-exports its subdomain subpackages, not only its direct modules: from . import bars, foos + the wildcards + __all__ = bars.__all__ + foos.__all__, so from myapp.domain import Foo resolves.
  • A subdomain package re-exports its whole public surface — entities, value objects, enums and type aliases; every i_*_repository.py and i_can_*.py protocol; domain services; and in application/, every command, query, result and handler.
  • The entrypoint package is a side-effect carve-out. restapi/__init__.py must not from .main import *, because importing main.py builds the application object; and the router package stays empty, because route modules each export a colliding router. A middleware package is not exempt — its class names are distinct, so it re-exports normally.
  • The declaration sets python-packaging's one-class test lets share a module are, here, two, and they are not one rule. The exception catalogue is a single file by principle — exception-catalog owns it, and it survives any framework. Grouping one resource group's wire schemas into a single module is a REST binding and belongs to hex-restapi-schema; a project with no HTTP surface has only the first.
  • Cross-layer imports are absolute, always: application/ reaching into domain/, restapi/ reaching into application/. Relative imports stay within one layer. This is python-packaging's across-a-package-boundary rule applied to the layer split, not a second rule.

Placing a use case

Outside in: the entry path in its entrypoint package, the handler in application/<subdomain>/, one protocol in domain/<subdomain>/ for each thing the handler needs from outside, one adapter per protocol under infrastructure/<technology>/ (hex-conventions), bound in containers.py and resolved by the entrypoint.

Moving code between layers

  • domain/ → application/ usually means the rule needed a protocol. Extract the protocol first, then move the orchestrator.
  • application/ → domain/ is rare, and correct only when the logic was pure all along: no IO, no protocol calls.
  • infrastructure/ → application/ almost never happens. If you feel the urge, you probably want to move the orchestration up and leave the adapter behind.
  • An entrypoint → application/ is correct when a second entrypoint needs the same logic. Pull it into a handler; the entrypoint becomes a thin translator.

Rules

The checkable form. Each one is decidable by reading a single import, signature or file path; the subsections beneath give the reasoning and the judgement calls.

  1. Check every import in domain/ resolves to domain/ or the standard library. Nothing else — no third-party package, not even a logger, and no other layer.
  2. Check application/ imports only domain/, stdlib and the logging library, and infrastructure/ only domain/, stdlib and third-party libraries — that last allowance is the layer's whole purpose, and the table above grants it. Neither imports the other, and neither imports an entrypoint. Only entrypoint packages may import all three.
  3. Check no import cycle exists between modules, subpackages or layers. A cycle always signals a layering violation: fix the structure, never paper over it with a type-checking-only or in-function import.
  4. Check each new module sits in the layer its work belongs to — pure logic in domain/, a rule needing a port in domain/ as a domain service, orchestration, id generation and business-event logging in application/, anything touching a datastore, filesystem, HTTP API or SDK in infrastructure/, anything that knows a transport in an entrypoint.
  5. Check every port is a typing.Protocol in domain/<subdomain>/, one per module, named I<Thing>Repository or ICan<Verb>.
  6. Check every handler constructor annotates a protocol type, not a concrete class. repository: IFooRepository, never repository: FooRepository.
  7. Check no adapter inherits from or imports the protocol it satisfies. Satisfaction is structural and is checked at the injection site; an adapter that imports the protocol it satisfies leaves an unused import and gains nothing.
  8. Check the composition root is the only module importing concrete adapters from infrastructure/ — one module, src/myapp/containers.py — and that it binds them at startup, not at import time. Entrypoints resolve handlers from the container per operation and never construct an adapter themselves.
  9. Check no module-level singleton holds a stateful resource — a connection, an engine, a client. Inject it.
  10. Check every cross-layer import is absolute and every within-layer import is relative.
  11. Check who logs against the layer table — nothing in domain/ or infrastructure/; application/ logs successes only, apart from a failed undo under compensation and a failed side effect after the store write. Every other error propagates to the entrypoint's central handler.

If you are tempted to import infrastructure from application (rule 2), you are wiring a concrete adapter where a protocol belongs — define the protocol in domain/ instead. If you are tempted to import application from infrastructure, you have an adapter that knows a use case — move the orchestration up to a handler.

Worth a firewall

Rules 1 and 2 are absolutes a grep can hold, so they earn a firewall (test-architecture-rule), one layer-scoped test per forbidden import:

  • no ORM, validation-library or other third-party import in domain/ (test_domain_has_no_sqlalchemy);
  • no infrastructure/ import in domain/ or application/;
  • no mock in tests (test-principles).

Hard stops

  • Whether hexagonal is the right family for this service is still open → stop, use architecture-choice before placing anything.
  • A packaging or import rule is being decided here → stop, python-packaging owns those; this skill adds only the layer-specific re-export rules above.