When is a dependency-injection container worth its cost over hand-written wiring, and how do you keep a large container-wired graph understandable?

## The decision is about where construction knowledge lives Every service has a **composition root**: the one place that knows how the whole object graph is assembled. The only question is whether that place is code a person wrote and the compiler checked, or a set of registrations a container interprets while starting. Both produce the same graph. The tradeoff is about verification, effort and readability — not about capability, and not about how loosely coupled the code is, which is decided by what constructors name. ## The axes that actually decide it - **Size and churn of the graph.** Hand-wiring is linear work that repeats; a container makes adding the twentieth service cost the same as the second. Below roughly a few dozen components with stable edges, the repetition is cheap and the indirection is not. - **When errors are caught.** Wiring written by hand is usually checked where it is written. Wiring interpreted at run time is checked when it resolves — later, and with a message about keys rather than about code. Containers that generate wiring ahead of time narrow that gap. - **How much construction is not the framework's choice anyway.** Handlers are constructed by the framework on demand; if it already resolves them through a container, hand-wiring only the rest leaves you with two composition roots, which is worse than either alone. - **Traceability.** "Which implementation is behind this parameter, and who decided?" is answered by reading a function in one case, and by searching registrations and inferring the match in the other. - **Start-up cost and cold starts.** Reflective graph construction is work done every time a process starts. Where instances start and stop constantly, that cost is paid repeatedly. - **Team familiarity.** Wiring that most of the team cannot predict is a tax on every change, regardless of which mechanism produced it. ## Where each one earns its keep | Situation | Leans toward | |---|---| | Small, stable graph; few services; start-up time is critical | Hand-written composition root | | Large graph, frequent additions, many shared collaborators | Container | | The framework already resolves handlers through a container | Container, used consistently | | Wiring must be verified before it runs, with no start-up check | Hand-written, or an ahead-of-time container | | Wiring differs per environment in more than a couple of places | Container, with the differences isolated | ## Keeping a large graph understandable Scale is what makes a container hard to read, so the practices worth enforcing all restore locality: 1. **One composition root.** Registration happens in wiring code, grouped by feature area, and nowhere else. A graph assembled in several unrelated places cannot be read at all. 2. **No lookups outside it.** Components take what they need as constructor parameters; nothing reaches into the container mid-request. This keeps every dependency visible in a signature and keeps the graph a graph rather than an ambient registry. 3. **Keep the graph shallow and acyclic.** Long chains make a single missing binding produce a deep, unreadable resolution path; rings make components inseparable. 4. **Prefer registrations a tool can read.** The more edges hide inside factory bodies, the less any validation can prove, and the more of the graph exists only in someone's head. 5. **Verify the graph automatically.** A fast check that resolves or validates every registration turns the container's own knowledge into a test, which is the cheapest insurance available. 6. **Name environment differences, not implementations.** Isolating the handful of registrations that differ per environment keeps the rest of the graph identical everywhere it runs. ## The failure mode to design against The bad end state is not "too many registrations". It is a graph nobody can trace: dependencies fetched mid-request instead of injected, edges buried in factories, registrations scattered across the codebase, and a resolution error whose path crosses ten components nobody owns. That state is reached gradually, and each individual step looks reasonable. The judgment a lead is expected to bring is therefore less "container or not" than **what must stay true about the graph as it grows**: construction lives in one place, dependencies are declared rather than fetched, the graph is acyclic, and something automated fails when it is not. A team that holds those four invariants can use either mechanism safely; a team that holds none will find a container amplifies the confusion faster than hand-wiring would.