Dependency Direction in Code

## What the arrows mean **"Dependency direction"** describes which way the compile-time references point between the parts of a codebase — literally, which files `import` or reference which other files. In a well-structured application you can draw the packages as concentric rings: - an **inner ring** holding business rules and domain models - a **middle ring** holding application/use-case orchestration - an **outer ring** holding technical details — web controllers, database access code, message-queue clients, third-party SDKs **"Pointing inward"** means every arrow you'd draw for an import statement goes from an outer ring toward an inner one, never the reverse. A controller class may import a use-case class; a use-case class may import a domain interface; but the domain package itself imports nothing from the controller or database packages. If you inspect the domain package's import statements and find `org.springframework` or `javax.persistence` or an HTTP client library, dependency direction has been violated, no matter how good the underlying business logic is. ## Why the rule exists This rule exists because it encodes a bet about what changes and what doesn't. | Stays put | Moves | |---|---| | Business rules — how a loan is approved, how a cart total is computed — tend to be relatively stable and are the reason the software exists. | Frameworks, databases, and external APIs are comparatively volatile: they get upgraded, replaced, or swapped for a competitor's product for reasons that have nothing to do with the business rules. | The **Dependency Inversion Principle** formalizes this as "depend on abstractions, not concretions," and the related **Stable Dependencies** idea adds the corollary that things should depend in the direction of increasing stability. If the domain package depends on the database package, then every time the database technology changes, the change pressure flows into the one part of the system you most want to protect. If instead the database package depends on interfaces defined by the domain, the database can be swapped, mocked, or reimplemented and the business rules never need to be touched, recompiled for a different reason, or even re-read. ## How the inversion works The mechanism that makes this possible despite runtime control flow going the "wrong way" is **dependency injection through an interface owned by the inner layer**. Say the `orders` use case needs to persist an order. 1. Instead of importing a `JpaOrderRepository` class directly, the use-case package declares an `OrderRepository` interface expressing only what it needs (`save(order)`, `findById(id)`). 2. The persistence package then depends on the use-case package to implement that interface with `JpaOrderRepository`. 3. At runtime, something at the edge of the system — a configuration class, a manual factory, a DI container — wires the concrete `JpaOrderRepository` into the use case. So calls still flow outward (the use case ends up invoking JPA code indirectly), but the source dependency points inward: the use-case package has zero import statements referencing JPA. ## The cost The cost of this discipline is real and worth naming honestly. Every port you introduce is: - an extra file - an extra layer of indirection - often an extra mapping step between the domain's shape and the outer layer's shape For a small CRUD app with one database and no plausible reason to swap it, this ceremony can slow a team down for no payoff — the abstraction has a cost but no realized benefit if nothing ever plugs in besides the one implementation. Teams need to weigh the likelihood of actually needing to substitute an implementation against the tax of the extra indirection on every change. ## Failure modes Failure modes show up gradually rather than as a single build error, because a single misplaced import doesn't break anything today. - The **classic symptom** is that unit-testing the core business logic becomes impossible without spinning up a real database, an application context, or a mocked HTTP server, because the "unit" under test transitively pulls in the framework. - **Another symptom** is that a seemingly small technology decision — upgrading an ORM, switching a payment provider — turns into a sprawling refactor that touches domain classes nobody expected to change. - **At the extreme**, enough inward-pointing violations accumulate that the dependency graph has cycles between what were meant to be layers, and the codebase degrades into what's colloquially called a "big ball of mud," where no part can be understood, tested, or changed in isolation. ## Ports and adapters A concrete, widely used embodiment of this idea is **Hexagonal (Ports and Adapters) Architecture**: the domain/application core defines "ports" (interfaces) for everything it needs from the outside world, and "adapters" — a REST controller, a JPA repository, a message consumer — live in outer packages and implement or call those ports. The core package can be compiled, tested, and reasoned about with zero framework dependencies on the classpath at all.