What are the concrete costs of adopting Onion Architecture for a project, and what kind of project would justify deliberately not using it?

## The bet you are making Every architectural pattern is a bet that a particular kind of future change is likely enough to be worth paying for up front, and Onion Architecture's bet is specifically that **business rules will outlive and diverge from infrastructure choices**. Evaluating whether to adopt it means being honest about whether that bet actually holds for the project at hand, and the costs are concrete enough to reason about explicitly rather than treating the pattern as an unconditional best practice. ## The three concrete costs 1. **The most direct cost is a multiplication of types and files** for every piece of behavior that crosses a ring boundary. Where a simple layered or transaction-script approach might have one class that both contains a business rule and calls the database directly, Onion Architecture wants an interface owned by the inner ring, a concrete implementation in the outer ring, and often a mapping layer to translate between a persistence representation and the domain model's own types, because the domain model is supposed to stay ignorant of how it's stored. For a feature with a handful of straightforward CRUD operations, this can mean three to five times the boilerplate for the same behavior, with no corresponding business-rule complexity to justify it. 2. **Second is an onboarding and review cost.** Engineers unfamiliar with the discipline write code that violates the inward-dependency rule by default — it's the natural thing to do, since directly calling a database from a service class is simpler to reason about locally — so the team either needs consistent review vigilance or automated architecture tests, both of which are ongoing costs, not one-time setup costs. 3. **Third, and easy to underestimate, is the risk of speculative generality.** Introducing a `PaymentGatewayPort` interface when there will only ever be one payment provider for the project's lifetime buys you nothing except an extra layer of indirection to step through when debugging, and 'we might switch providers someday' is a weak justification if it's not actually on a roadmap. ## When the pattern earns its cost back The pattern earns its cost back specifically when two conditions hold together. 1. **First, business logic complexity.** If the domain has real invariants, multi-step workflows, and rules that a domain expert would recognize and argue about, keeping that logic isolated and heavily unit-tested pays for itself quickly, both in test suite speed and in confidence that a refactor of the persistence layer can't silently break a business rule. 2. **Genuine infrastructure volatility.** Systems that must support multiple deployment targets (an on-prem version and a cloud SaaS version with different databases), systems undergoing a planned technology migration, or systems where the team wants to defer an infrastructure decision until later while still making progress on business logic, all get direct value from the inward-dependency discipline because the volatility it's designed to isolate is real and known in advance, not hypothetical. ## The projects that should skip it Conversely, the projects that should deliberately skip Onion Architecture, or adopt a much lighter version of it, are ones where neither condition holds. - **A small internal admin CRUD tool** — say, a form that lets support staff edit a handful of database rows — has essentially no business logic beyond validation, so there's no meaningful 'core' to protect, and the database is never going to change for the tool's lifetime. - **A short-lived prototype or MVP** built to validate a product hypothesis is explicitly optimizing for speed of learning over long-term maintainability; if the hypothesis fails, the code is deleted regardless of how well-isolated the domain was, and if it succeeds, refactoring toward more structure once the shape of the real business logic is actually known is often cheaper than guessing at the right abstractions up front. - **A batch job or ETL script** whose entire job is 'read from A, transform, write to B' has no domain model to protect in the Onion sense — the 'transform' step is usually straightforward data mapping, not business rules with invariants. - **A small or junior-heavy team** without the bandwidth to maintain the discipline often ends up with the worst of both worlds: all the ceremony of extra interfaces and mapping code, without ever actually keeping the dependency rule intact, because nobody enforces it — Onion Architecture badly executed can end up strictly worse than a straightforward layered design honestly executed. ## The signal to watch for Finally, a well-known real-world signal of this trade-off in practice: many teams that start a greenfield service with full onion/hexagonal ceremony end up quietly collapsing back toward a simpler layered structure once the actual feature set turns out to be mostly CRUD with a handful of validation rules — the correct move is recognizing that early rather than continuing to pay the ceremony tax for years.