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.mdplugins/pyhouse-hex/skills/hex-architecture/SKILL.md
GitHubHexagonal 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 thepyhouse-flatplugin. 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-packagingfor 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__.pycontract, 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/, noinfrastructure/, 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 indomain/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-wiringrule 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.pyat 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-deliveryrules 1 and 2) — mapped from its class here and never stored on it indomain/, with any body read off the exception's own attributes (exception-catalogrules 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-deliveryrule 3): a create a delivered unit drives is written to resolve a conflict on its own identity as nothing to do (persistencerule 15), the statement beinghex-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 — isat-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__.pystays empty —python-packaging's carve-out for an application's root, with a layered reason: aggregating the layer subpackages to the root would makeimport <package>transitively pull infrastructure and entrypoint third-party dependencies on every use, and would destroy the dependency-freedomain/applicationimport 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__, sofrom myapp.domain import Fooresolves. - A subdomain package re-exports its whole public surface — entities, value objects, enums and type
aliases; every
i_*_repository.pyandi_can_*.pyprotocol; domain services; and inapplication/, every command, query, result and handler. - The entrypoint package is a side-effect carve-out.
restapi/__init__.pymust notfrom .main import *, because importingmain.pybuilds the application object; and the router package stays empty, because route modules each export a collidingrouter. 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-catalogowns it, and it survives any framework. Grouping one resource group's wire schemas into a single module is a REST binding and belongs tohex-restapi-schema; a project with no HTTP surface has only the first. - Cross-layer imports are absolute, always:
application/reaching intodomain/,restapi/reaching intoapplication/. Relative imports stay within one layer. This ispython-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.
- Check every import in
domain/resolves todomain/or the standard library. Nothing else — no third-party package, not even a logger, and no other layer. - Check
application/imports onlydomain/, stdlib and the logging library, andinfrastructure/onlydomain/, 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. - 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.
- Check each new module sits in the layer its work belongs to — pure logic in
domain/, a rule needing a port indomain/as a domain service, orchestration, id generation and business-event logging inapplication/, anything touching a datastore, filesystem, HTTP API or SDK ininfrastructure/, anything that knows a transport in an entrypoint. - Check every port is a
typing.Protocolindomain/<subdomain>/, one per module, namedI<Thing>RepositoryorICan<Verb>. - Check every handler constructor annotates a protocol type, not a concrete class.
repository: IFooRepository, neverrepository: FooRepository. - 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.
- 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. - Check no module-level singleton holds a stateful resource — a connection, an engine, a client. Inject it.
- Check every cross-layer import is absolute and every within-layer import is relative.
- Check who logs against the layer table — nothing in
domain/orinfrastructure/;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 indomain/orapplication/; - no mock in tests (
test-principles).
Hard stops
- Whether hexagonal is the right family for this service is still open → stop, use
architecture-choicebefore placing anything. - A packaging or import rule is being decided here → stop,
python-packagingowns those; this skill adds only the layer-specific re-export rules above.