Layering

## What layering is **Layering** is a *structural style*: you partition a system into ordered groups of components ("layers") and impose a rule about which group may depend on which. In classic layering the partitioning criterion is *technical role* — what kind of work the code does — rather than *feature* (checkout, billing) which is the criterion used by vertical-slice or modular decompositions. A **dependency** here means any compile-time or link-time knowledge: an import, a type reference, a direct call, an inherited base class. "A depends on B" means A cannot compile or run without B being present. ## The canonical three (or four) layers 1. **Presentation / interface layer** — everything that adapts the outside world to the application. Web controllers, GraphQL resolvers, CLI commands, message-queue listeners, HTML templates, mobile views. Responsibilities: parse and validate the *shape* of input, authenticate/authorize at the edge, map request payloads (**DTOs** — Data Transfer Objects, dumb structures whose only job is to carry data across a boundary) into domain-meaningful arguments, and translate results and errors back into a protocol (HTTP status, JSON, screen state). 2. **Application layer** (often merged into the domain layer, sometimes separate) — orchestrates use cases: "place order" = load customer, check credit, create order, publish event, commit transaction. It owns transaction boundaries and sequencing, not business rules themselves. 3. **Domain / business layer** — the rules and the vocabulary of the problem. Entities, value objects, invariants ("an order total can never be negative"), policies, calculations, state machines. This is the layer whose value survives a rewrite of the UI or a database migration. 4. **Infrastructure / persistence layer** — technical mechanisms: SQL, ORM mappings, file and blob storage, HTTP clients to third parties, message brokers, email/SMS gateways, caches, clocks, random-number sources. Some teams also name a **data-access layer** separately from a broader infrastructure layer; the count matters far less than the ordering and the rule. ## The dependency-direction rule The rule is: **references flow in exactly one direction, downward through the ordering, and never back up.** Presentation may know about domain types; domain must not know that an HTTP controller exists. Infrastructure may know domain types (to persist them); it must not invoke business decisions. Why it matters: - **Testability.** A domain with no I/O dependency can be unit-tested in memory, with no database, network, or container. - **Replaceability.** You can add a CLI beside the web UI, or move from one database to another, touching only the layer that changed. - **Comprehensibility.** Cycles between layers make a system impossible to reason about or build incrementally; a one-way graph gives you a build order and a reading order. - **Change isolation.** Volatile things (frameworks, protocols, vendors) live at the edges; stable things (business rules) live in the middle. ## How information gets back upward Beginners often object: "but the repository has to tell the service something." Upward *information* flow is fine; upward *dependency* is not. Legal mechanisms: - **Return values and exceptions** — the caller pulled, so no upward reference exists. - **Callbacks / higher-order functions** the lower layer accepts as parameters. - **Observer or event notification** where the *event type* and the *listener interface* are owned by the lower layer, and the upper layer registers itself. Classic layering literature calls this the standard technique for layer-upward communication. - **Dependency inversion**: the *upper* layer declares an interface it needs, and the lower layer implements it. This flips the compile-time arrow while keeping runtime call direction. It is the basis of hexagonal/ports-and-adapters and "clean" architecture, where infrastructure depends on the domain rather than the reverse. ## Two orderings you will see - **Classic layering:** presentation → application → domain → infrastructure. Domain depends on the persistence abstraction. - **Dependency-inverted (onion/clean/hexagonal) layering:** domain sits at the center and depends on nothing; both presentation and infrastructure depend inward on the domain. The repository *interface* lives in the domain; the JDBC/ORM implementation lives in infrastructure. Both are "layered"; the second is strictly better for protecting the domain and is what most modern answers should describe, while acknowledging the classic form. ## Logical layers vs. physical tiers **Layers** are a code/compile-time concept. **Tiers** are deployment units (browser, app server, database server). A three-layer application very often runs in one process — layering does not imply network hops, and confusing the two leads people to think layering is inherently slow. ## Common failure modes - Domain classes annotated with ORM/serialization/framework annotations, so the "pure" layer silently depends on infrastructure. - Controllers containing business rules, leaving an anemic domain layer that is just data holders. - A repository interface whose method names leak SQL or paging details (`findByRawQuery`), so callers become coupled to storage. - Layers enforced only in documentation, with nothing in the build stopping a violation. ## Trade-offs Layering is cheap to teach, gives a stable place for everything, and matches most frameworks' defaults. It costs indirection: a trivial field addition can require edits in DTO, mapper, domain object, repository, and schema. It also groups code by *what it is* rather than by *what it is for*, so a single feature is smeared across the codebase — which is exactly the complaint that motivates vertical-slice and modular alternatives.