Dependency inversion

The two halves of DIP

Robert Martin’s Dependency Inversion Principle has two statements, and both must hold:

1. High-level modules should not depend on low-level modules. Both should depend on abstractions.
2. Abstractions should not depend on details. Details should depend on abstractions.

The first statement is familiar — it is the dependency rule from the previous lesson in module form. High-level modules (billing, in the B2B platform) contain the policy: the business logic that decides what should happen. Low-level modules (the order repository, the payment gateway) contain the mechanism: the technical plumbing that makes it happen. Policy should not be coupled to mechanism.

The second statement is the subtle one — and it is what the opening story got wrong. Putting the interface in the low-level module’s package makes the abstraction a detail of the low-level module. The high-level consumer imports the interface from the low-level module. The low-level module can still break the consumer by restructuring its package, renaming its interface, or splitting it into multiple interfaces. The abstraction is technically present, but ownership has not been inverted.

The DIP requires that the high-level module own the abstraction it depends on.

Who owns the interface?

Interface ownership is the core of DIP. An interface is owned by whoever defines it and controls its evolution. When you ask “should this interface change?”, the answer should come from the consumer’s needs, not from the provider’s implementation convenience.

In the B2B platform, the billing module needs order data. The interface it needs — IOrderProvider or IOrderPort — should live in billing’s package (or in a shared boundary package that billing controls). It declares exactly what billing requires: getConfirmedOrder(id: string): Promise<ConfirmedOrderDTO>. Nothing more. The order module then implements this interface by writing a class that satisfies billing’s contract.

The dependency arrows now run:

BillingService   ──imports──→   IOrderPort   (owned by billing)
                                      ↑
                              implements
                                      │
                         PostgresOrderRepository   (in order module)

The order module’s repository depends on billing’s interface — not the other way around. If billing’s needs change, the interface changes and the repository must update. If the order team changes how they fetch order data internally, they update their repository implementation; billing’s interface is untouched.

The compile-time boundary vs the runtime boundary

DIP is fundamentally about drawing a boundary that the compiler can enforce. On one side of the boundary: the high-level module and the interface it owns. On the other side: the low-level module that implements it. Neither side needs to know about the other’s concrete details.

This distinction between what can be known at compile time and what is resolved at runtime is the key to modularity:

At compile time, BillingService only knows about IOrderPort. It knows the method signatures, the parameter types, the return types. It knows the contract. It does not know that PostgresOrderRepository exists. The compiler cannot even see PostgresOrderRepository from billing’s perspective.

At runtime, something must wire IOrderPort to PostgresOrderRepository. This is the job of dependency injection: a composition root or a container resolves which concrete implementation satisfies which interface, and passes it to billing. At that moment, control flows from billing through the interface to the repository implementation.

This separation is the core of what makes architectural patterns like hexagonal architecture (unit 04) and clean architecture (unit 05) work. The hexagon in hexagonal architecture is the high-level domain, surrounded by interface definitions it owns (ports). Adapters — the concrete implementations — live outside the hexagon and depend on the ports inward. The concentric circles in clean architecture are layers where each inner circle owns the interfaces that outer circles implement. DIP is the mechanism that makes those patterns structurally enforceable.

DIP in the B2B order platform: a before/after

Before DIP, the B2B platform had this structure:

• billing/ imports order/infra/postgres-order-repo.ts → concrete-to-concrete
• billing/ imports payment/stripe-gateway.ts → concrete-to-concrete
• order/ imports db/postgres-driver.ts → concrete-to-concrete

Every module could break every other module through implementation changes. Adding a new payment provider required changing billing. Swapping the database required touching everything.

After DIP:

• billing/ports/IOrderPort.ts — owned by billing; defines getConfirmedOrder
• billing/ports/IPaymentPort.ts — owned by billing; defines chargeCustomer
• order/adapters/BillingOrderAdapter.ts — implements IOrderPort, lives in order module but depends on billing’s interface
• payment/adapters/StripePaymentAdapter.ts — implements IPaymentPort, lives in payment module but depends on billing’s interface

Billing now has zero compile-time knowledge of the order module’s internals or the payment module’s internals. The order and payment modules depend on billing’s boundary definitions. Adding a new payment provider means writing a new adapter that implements IPaymentPort — billing itself does not change.