In Onion Architecture, why is the domain model placed at the center of the design instead of the database or UI?

## The rings, from the center outward Onion Architecture, coined by **Jeffrey Palermo** in 2008, structures an application as a series of concentric rings drawn around a domain model at the very center. Moving outward, the typical rings are: - **the domain model itself** — entities, value objects, and the invariants that govern them; - **domain services** — business logic that doesn't naturally belong to a single entity, e.g., calculating whether two bookings conflict; - **application services** — orchestration code that represents a use case — 'place an order', 'transfer funds' — that coordinates domain objects, repositories, and other application services; - **and finally the outermost ring**, infrastructure and presentation, containing the database access code, the web controllers, message queue adapters, the UI, and any third-party SDKs. ## The mechanism that makes it work The mechanism that makes this work is the **Dependency Inversion Principle** applied at the architectural scale, not just the class scale. Compilation and import dependencies are only allowed to point inward: a file in an outer ring may import and depend on types defined in an inner ring, but never vice versa. Concretely, if the application service needs to save an `Order`, it does not call a SQL library or an ORM directly. Instead: 1. The inner ring declares an interface — say, `OrderRepository` — with methods like `save(order: Order)` and `findById(id): Order?`. That interface lives inside the ring that needs it. 2. The outer infrastructure ring then provides a concrete implementation, e.g., `JpaOrderRepository`, which depends on the domain's `Order` type and on the interface it implements, but the domain never imports JPA, Hibernate, or a JDBC driver. 3. At runtime, a dependency injection container wires the concrete implementation into the abstraction, so the flow of control still reaches the database, but the flow of source-level dependency has been inverted: the database module depends on the domain's contract, not the other way around. ## Different rates of change Why does this exist? Different parts of a system change at different rates and for different reasons. | What it is | Why it changes | |---|---| | Business rules — what counts as a valid order, how a shipping discount is computed | change because the business changes | | Infrastructure — which database engine you use, which web framework serves HTTP, which cloud provider hosts your queue | changes because of technical decisions, vendor migrations, performance needs, or fashion | If your business logic imports and depends on infrastructure types, then every infrastructure churn forces a review and possible rewrite of business logic, and every business change risks being entangled with technical plumbing. Onion Architecture decouples these change rates by making the volatile ring depend on the stable ring, never the reverse. A second, related benefit is **testability**: because the domain and application layers have no reference to a live database or HTTP server, you can unit-test the bulk of business logic in memory, in milliseconds, using fake or in-memory implementations of the repository interfaces — no test containers, no network calls. ## The trade-offs The trade-offs are real and worth naming honestly. - **Ceremony.** There is a genuine increase in the number of types and indirection: an interface in the domain, a mapping layer at the boundary, and a concrete adapter in infrastructure, where a simpler layered approach might have had one class. For a small CRUD app or a short-lived prototype, this ceremony can slow initial development without paying for itself, because the presumed volatility of infrastructure never materializes before the project is retired. - **Judgment calls.** Drawing the ring boundaries also requires judgment calls that are easy to get wrong — teams often misclassify what's 'domain' versus 'application' logic, causing friction and bikeshedding in code review. - **Leaky inversion.** And if the abstractions are designed poorly — e.g., a repository interface that leaks a SQL-specific concept — you get a 'leaky' inversion that provides ceremony without the actual benefit, since the domain is still implicitly coupled to infrastructure assumptions. ## How it erodes in production The most common production failure mode is **architectural erosion**: the rule is enforced by discipline and code review, not by the compiler, so over time a developer under deadline pressure imports an ORM entity annotation directly onto a domain class, or an application service calls out to a payment gateway SDK directly instead of through a port interface, because 'it's just this one time.' Months later, dependency inversion has silently collapsed in half the codebase, and nobody notices until a database migration or a framework major-version bump forces a costly untangling. Teams that take Onion Architecture seriously usually pair it with **automated enforcement** — tests that fail the build if an inner-ring file imports an outer-ring package: - `ArchUnit` in the JVM world; - `dependency-cruiser` in the JS/TS world. A well-known real-world illustration is any Spring codebase where JPA-annotated entity classes are deliberately kept separate from pure domain classes, precisely so the domain module has zero Spring or JPA imports, which is the onion rule enforced in practice.