← All patterns
Application structure · Architecture pattern

Clean, Hexagonal & Onion

Compare three ways to protect business rules through inward-facing source dependencies.

The problem

A domain rule needs a database driver and a web framework just to run a unit test.

When it fits

Long-lived business logic benefits from stable boundaries around replaceable transport and persistence details.

The whole architecture

Architecture diagram

Adapters depend on core-owned ports, while domain rules remain independent of transport and storage details.

Every green arrow is a source-code dependency, not runtime request direction.

100%

Scroll to pan. Select a component for its role.

clean hexagonal onion architectureAdapters depend on core-owned ports, while domain rules remain independent of transport and storage details. Every green arrow is a source-code dependency, not runtime request direction.Application core: contracts and policyIndependent domainReplaceable adaptersInfrastructure adapterTest adapterhttp → input: importsusecase → input: implements contractusecase → repository: depends on portusecase → domain: business rulesstorage → repository: implements porttests → input: drives coreimportsimplements contractdepends on portbusiness rulesimplements portdrives coreTranslate a transport request into the application contract.HTTP adapterTransport / validationThis contract belongs to the core, rather than to the transport framework.Input portUse-case contractCoordinate domain behavior through core-owned contracts.Use casesApplication behaviorDomain rules do not import concrete adapters or framework types.Domain modelBusiness rulesThe core specifies the required storage behavior.Storage portCore-owned interfaceImplement the core interface and keep driver-specific details outside.SQL adapterPort implementationA test can drive a port or substitute an implementation without a real database.Test adapterIn-memory implementationClean, Hexagonal and Onion have related principles with different emphases.Dependency principleSource dependencies point inward; runtime calls can dispatch outward through a port

Select a component, or focus it and press Enter, to read its role.

Walk through the design

Follow one operation

Select a step to highlight its participants. This conceptual walkthrough is separate from challenge scoring.

Arrows show source-code imports toward the core, not runtime request flow. The storage adapter depends on a core-owned port.

Transport adapterActive in this stepUse-case coreActive in this stepDomain modelWaitingStorage adapterWaiting
Step 1 of 3

Translate at the boundary

Transport adapts a request to a use case. Its source code imports the inward-facing application contract.

Application structure

Compare the approaches

Related principles, different design emphasis
ApproachEmphasisBoundary contract
CleanEntities and use cases with boundaries around interface adapters and frameworks.Define boundary contracts on the side that owns the business policy.
HexagonalPorts represent application interactions; adapters connect UI, storage, tests and other devices.Keep the application usable through a port while swapping the outside adapter.
OnionAn independent domain model at the center, surrounded by application behavior and infrastructure.Inner layers define interfaces and outer layers implement them.

Repair the source dependencies

The initial use-case module imports concrete storage. Select the imports that keep the required boundary contracts while pointing toward the core. Compare your choices with the source-import diagram above.

Source module → imported module

This local exercise checks the declared import graph. It awards no points and makes no claim about runtime behavior, framework integration or service capacity. Reloading resets it.

Trade-offs to make explicit

  • Core-owned contracts allow adapters to change while business rules remain testable in isolation.
  • The approaches emphasize different boundaries; extra interfaces and mapping code should earn their maintenance cost. Simple applications may need fewer boundaries.

Failure modes to plan for

  • A core module importing a concrete SQL adapter makes infrastructure a source dependency again.
  • A named port still leaks infrastructure if its types expose ORM sessions or transport-specific request objects.
Before you build

Explain your decision

Who owns a persistence port, and how can a runtime call reach an adapter while the source dependency points inward?

Use Plan & estimate inside practice to record your assumptions and trade-offs.

Connect concept to practice

Related challenges

Browse challenges →

These links open the original challenges. Existing round unlocks, completions and points apply.

Keep one responder on duty

Related business-invariant practice. Module imports and dependency inversion are checked locally in the lesson exercise, not by the practice canvas.

Open challenge →

Further reading

Robert C. Martin · Clean Architecture ↗

Alistair Cockburn · Hexagonal architecture ↗

Jeffrey Palermo · Onion Architecture ↗

Original PractiseGrid explanations and conceptual diagrams, with primary references for further study. Dedicated scored exercises can be added as coverage grows.