# Composition Root
The **Composition Root** is the *single place* in an application where all object graphs are wired together. It's the one location that knows how to construct concrete classes; everywhere else only sees abstractions. Term and rule come from [[Mark Seemann]] (*Dependency Injection in .NET*, 2011).
The rule: **resolve dependencies at the application's entry point — and nowhere else.**
For a CLI: in `main()`. For a web app: in the bootstrapper that runs before the first request. For a library: there is no Composition Root — libraries should never have one (they're consumed *by* an app, which owns the wiring).
## Why it matters
- **One place to reason about wiring**. If you want to know "what is the database in production?", there's exactly one file to look at.
- **Concretes are confined**. The rest of the codebase imports only interfaces / abstractions, satisfying the [[Dependency Inversion Principle (DIP)]].
- **Test substitution is trivial**. A test composition root wires fakes; production wires real implementations. No code under test changes.
- **No hidden globals**. Without a Composition Root, the alternative is usually [[Service Locator]] or static singletons — both of which scatter dependency decisions across the codebase.
## What it looks like
```
// main.ts (the Composition Root — and the only place with `new` for these classes)
const db = new PostgresClient(env.DATABASE_URL)
const cache = new RedisCache(env.REDIS_URL)
const repo = new OrderRepository(db, cache)
const emailer = new SendgridEmailer(env.SENDGRID_KEY)
const orderService = new OrderService(repo, emailer)
const app = new HttpApi(orderService)
app.listen(8080)
```
Everything below `main` receives its collaborators through constructors. `OrderService` cannot reach for the database; the database is *given* to it.
## Pure DI vs container DI
A Composition Root can be:
- **Pure DI** ("Poor Man's DI") — manual `new` calls, like the example above. Best default. Easy to type-check, fast to start, errors visible at compile time.
- **Container-based** — Spring, Angular's injector, NestJS, Guice, .NET's `IServiceCollection` register types and resolve them via reflection or codegen. The Composition Root becomes the container *configuration*, not a chain of `new` calls.
Either way, the principle is the same: *one* place wires the graph. A container that's queried throughout the codebase has stopped being a Composition Root and has become a [[Service Locator]] in disguise.
## The "as close to the entry point as possible" rule
If a class deeper in the system constructs concrete dependencies, it has become a *secondary* Composition Root — and the rules of one Composition Root are violated. Symptoms:
- Constructor of `class Foo` does `new Bar()` for a non-trivial Bar.
- A factory inside the domain model constructs infrastructure.
- A unit test has to reach into a class to swap a private field because the class created its own collaborator.
All three indicate dependencies are being wired in the wrong place. Move the construction up to the entry point and pass the result down.
## Frameworks that own the Composition Root for you
In some platforms — Spring Boot, ASP.NET, NestJS, Angular — the framework *is* the Composition Root: it scans annotations / decorators, builds the graph, and hands you the wired-up application. You configure it; you don't construct it. The principle still applies: configuration of those containers belongs in startup code, not scattered across modules.
## Smell: "I need to inject a dependency 8 layers deep"
If passing a dependency from the Composition Root down to a leaf requires threading it through many intermediate constructors that don't use it, you may have a deeper design issue (the leaf is doing too much, or the intermediate layers don't form a coherent domain). Don't reach for [[Service Locator]] to "solve" this — fix the structure.
## References
- Mark Seemann — *Composition Root* (2011) — https://blog.ploeh.dk/2011/07/28/CompositionRoot/
- Mark Seemann — *Dependency Injection Principles, Practices, and Patterns* (Manning, 2019)
## Related
- [[Dependency Injection (DI)]]
- [[Dependency Inversion Principle (DIP)]]
- [[Inversion of Control (IoC)]]
- [[Service Locator]]
- [[Loose Coupling]]
- [[SOLID Principles]]
- [[Mark Seemann]]