Clean Architecture & Hexagonal Architecture Vocabulary
Clean Architecture layers, ports and adapters, dependency rule, use cases, and architectural boundary vocabulary.
Software architecture has its own precise vocabulary. When your team debates whether business logic belongs in a controller, or whether a database ORM is leaking into your domain model, you need the right words to make the argument clearly. This guide covers the essential English vocabulary for Clean Architecture, Hexagonal Architecture, and related patterns — so you can discuss design principles confidently in code reviews, design sessions, and engineering interviews.
Core Terms
Clean Architecture — a layered architectural style popularised by Robert C. Martin (Uncle Bob) in his 2017 book of the same name. It organises code into concentric circles, with the most stable, business-critical code at the centre and framework-specific details on the outside. The goal is to keep your core logic independent of databases, UI frameworks, and external services.
“We need to refactor this module — the business logic is directly coupled to the database. Let’s apply clean architecture and push the persistence concern outward.”
“In clean architecture, the inner layers know nothing about the outer ones. Your domain model should never import a Spring annotation.”
Uncle Bob — the nickname of Robert C. Martin, a prominent software engineer and author. Developers commonly refer to him by this name in conversation. He is also associated with the SOLID principles, which underpin much of clean architecture thinking.
“Have you read Uncle Bob’s talk on screaming architecture? It completely changed how I think about folder structure.”
Hexagonal Architecture (Ports & Adapters) — an architectural pattern introduced by Alistair Cockburn. It describes an application as a hexagon with a core business logic at the centre. The outside world communicates with the core through ports and adapters. It solves the same problem as clean architecture but uses different terminology. You will often see the two names used interchangeably in practice.
“We’re using hexagonal architecture — the domain doesn’t know whether it’s talking to a real database or an in-memory fake. The adapter handles that.”
Onion Architecture — a closely related pattern described by Jeffrey Palermo. Like clean architecture, it uses concentric layers with domain logic at the centre. The name reflects the layered, ring-shaped structure. Teams sometimes use “onion”, “hexagonal”, and “clean” as rough synonyms.
“Our onion architecture broke down when someone put an HTTP client call directly inside the domain service. That’s exactly the kind of coupling we were trying to prevent.”
Layers and Boundaries
Layer — a ring or tier in the architecture that groups code by its role and its distance from the business core. Clean architecture defines four canonical layers (from innermost to outermost): entities, use cases, interface adapters, and frameworks & drivers.
“This validation logic shouldn’t sit in the controller layer — it belongs in the use-case layer at the latest, or in the entity itself.”
Entity — the innermost layer; it contains enterprise-wide business rules and domain objects. Entities are plain objects (or classes) that encapsulate the core data and behaviour of your domain. They have no awareness of databases, HTTP, or any framework.
“The
Orderentity enforces the rule that an order cannot be placed with a zero quantity. That rule lives in the entity because it’s true regardless of which channel the order comes through.”
Use Case — the second layer inward; it contains application-specific business rules. A use case orchestrates entities to fulfil a single user goal (e.g., “place order”, “cancel subscription”). Use cases are sometimes called interactors in Uncle Bob’s original writing.
“I’m writing a use case for the checkout flow. It calls the inventory gateway to check stock, then the payment gateway, then saves the order. No HTTP code touches it.”
Interface Adapters — the third layer; it converts data between the format convenient for use cases and entities, and the format required by external systems (databases, web frameworks, message queues). Controllers, presenters, and gateways live here.
“The interface adapter layer is where we serialise the domain object into a JSON response. The use case itself returns a plain data structure — the presenter formats it.”
Frameworks & Drivers — the outermost layer; this is where all the framework-specific and I/O code lives: Express or Django routing, ORM configuration, message-broker clients. These are the most volatile parts of the system — frameworks change, your business logic should not.
“We can swap out our database ORM in the frameworks layer without touching a single line of business logic. That’s the whole point.”
Architectural Boundary — a deliberate interface that separates one layer from another and enforces the dependency rule. Crossing a boundary should always go in the same direction: inward. Architectural boundaries are often enforced using interfaces (in statically typed languages) so that the inner layer depends on an abstraction, not a concrete implementation.
“We drew a hard architectural boundary between the use-case layer and the database. Anything that crosses that boundary must go through an interface.”
Dependency Rule — the fundamental constraint of clean architecture: source code dependencies must point inward. An outer layer may depend on an inner layer, but an inner layer must never depend on an outer layer. This rule is what makes the core logic testable and independently deployable.
“Your use case is importing a Hibernate entity class. That violates the dependency rule — persistence types should never leak into the domain.”
Ports, Adapters, and Supporting Roles
Port — in hexagonal architecture, a port is an interface that defines how the application communicates with the outside world. There are two kinds: primary ports (also called driving ports) define how external actors call into the application (e.g., an HTTP controller calls a use-case interface). Secondary ports (also called driven ports) define how the application calls outward to infrastructure (e.g., a repository interface for database access).
“Define a secondary port — a repository interface — then write two adapters: one for Postgres, one for an in-memory list. Your tests use the in-memory adapter and never touch the database.”
Adapter — a concrete implementation of a port. An adapter knows how to translate between the domain-facing interface and a specific technology. An HTTP adapter translates an incoming web request into a use-case call. A database adapter implements a repository interface using SQL or an ORM.
“We wrote a Stripe adapter that implements our
PaymentGatewayport. If we ever switch payment providers, we just write a new adapter — the use case stays unchanged.”
Gateway — a common name for a secondary adapter that wraps an external service or data store. A repository gateway handles database access; an email gateway wraps an email provider. Some teams use “gateway” and “adapter” interchangeably in the context of outgoing integrations.
“The gateway encapsulates all the SQL queries. The use case just calls
userGateway.findById(id)and gets back a domain object.”
Presenter — an interface adapter responsible for formatting the output of a use case into a view model (JSON, HTML, or any other format). The use case calls the presenter with raw output data; the presenter transforms it for the delivery mechanism. This pattern keeps formatting logic out of the business layer.
“The presenter converts the domain
Moneytype into a localised currency string. The use case has no idea how the amount will be displayed.”
Screaming Architecture — a concept from Uncle Bob: the top-level structure of a codebase should scream what the system is about (e.g., “health care system”, “loan management”), not what framework it uses. If opening a project and seeing only controllers/, models/, views/ tells you nothing about the business domain, the architecture is not screaming.
“When I cloned the repo, the folder structure just said ‘MVC’. It didn’t tell me anything about the business. Uncle Bob would say it’s not screaming architecture.”
Coupling, Cohesion, and Design Quality
Coupling — the degree to which one module depends on another. High coupling means a change in one place forces changes elsewhere. Clean architecture actively reduces coupling between layers by enforcing the dependency rule and using interfaces at boundaries.
“The reason this refactor is so painful is high coupling between the service layer and the ORM models. We need to introduce a mapper to break that dependency.”
Cohesion — the degree to which the elements inside a module belong together. High cohesion means a class or module does one thing well; low cohesion means it mixes unrelated responsibilities. Good architecture aims for high cohesion within layers and low coupling between them.
“This
UserServicehas low cohesion — it handles authentication, profile updates, and email notifications. Let’s split it into three focused use cases.”
How to Use These Terms in Conversation
Architecture vocabulary is most useful when it is precise and shared. Here are some natural patterns for common situations.
In a code review:
“This controller is doing too much — it’s fetching data, running calculations, and formatting the response. The calculation belongs in a use case, and the formatting belongs in a presenter.”
In a design session:
“Before we start coding, let’s agree on our ports. We need a primary port for the REST API to call into, and two secondary ports — one for the database and one for the notification service.”
When explaining the architecture to a new team member:
“We follow hexagonal architecture. The domain model in the centre knows nothing about Spring or Postgres. Everything that touches the outside world goes through an adapter that implements one of our port interfaces.”
When pushing back on a shortcut:
“I know it’s quicker to call the repository directly from the entity, but that violates the dependency rule. Let’s keep the database concern in the interface-adapter layer.”
Quick Reference
| Term | Layer / Role | Plain English Definition |
|---|---|---|
| Clean Architecture | Architectural style | Concentric layers; business logic at the centre, frameworks on the outside |
| Dependency Rule | Core principle | Dependencies always point inward; inner layers never import outer ones |
| Entity | Innermost layer | Domain object with enterprise-wide business rules |
| Use Case | Second layer | Application-specific logic that orchestrates entities for one user goal |
| Port | Boundary interface | Interface defining how the app communicates with the outside world |
| Adapter | Outer layer | Concrete implementation of a port; translates between domain and technology |
| Gateway | Interface adapter | Adapter wrapping an external data store or service |
| Presenter | Interface adapter | Formats use-case output into a view model for the delivery mechanism |
| Coupling | Design quality | Degree of dependency between modules (lower is better) |
| Cohesion | Design quality | Degree to which a module’s elements belong together (higher is better) |