Wiring and the Composition Root

1// composition/graph.ts — the only place that says `new`
2export function buildGraph(cfg: Config, o: Overrides = {}) {
3  const pool     = o.pool     ?? new PgPool(cfg.databaseUrl, cfg.poolSize)
4  const clock    = o.clock    ?? new SystemClock()
5  const gateway  = o.gateway  ?? new StripeGateway(cfg.stripeKey, cfg.timeoutMs)
6  const orders   = new PgOrderRepository(pool)
7  const audit    = cfg.auditEnabled ? new DbAuditLog(pool) : new NoopAudit()
8 
9  return {
10    placeOrder: new OrderService(gateway, orders, clock),
11    refund:     new RefundService(gateway, orders, audit),
12    close:      () => pool.end(),
13  }
14}
15 
16// api/main.ts     const g = buildGraph(loadConfig())
17// worker/main.ts  const g = buildGraph(loadConfig(), { pool: new PgPool(url, 4) })
18// test helper     const g = buildGraph(testConfig(), { gateway: fakeGateway, clock: fixedClock })

The worker line is the whole argument. Its only intended difference from the API is a smaller connection pool, and here that difference is four visible words instead of a second forty-line file that nobody diffs. The test helper uses the same builder, so tests exercise the production graph rather than an imitation of it.

1. 1
   Load configuration

   Read environment, files and secrets into one typed value. Nothing else may read the environment after this point.

   fails by Scattered process.env reads mean a missing variable is discovered by whichever request first needs it, hours after deploy (Hidden Global State).

2. 2
   Validate configuration

   Parse and check every value — URLs, timeouts, key formats — and exit non-zero with a readable message on failure.

   fails by Validating lazily turns a deploy-time error into a runtime error, and a typo in a rarely-used setting survives to production (Validate at Startup, Fail Loudly).

3. 3
   Open external resources

   Connection pools, message-broker channels, caches. Verify one connection actually works rather than assuming.

   fails by Lazy connections make a wrong database URL look like a healthy process until the first query (Connection Pools).

4. 4
   Build the object graph

   One buildGraph(cfg, overrides) call. Under manual wiring the compiler has already proven this can succeed.

   fails by Under a container, a missing registration surfaces here at best and on first resolution at worst — which is why the startup resolve test exists.

5. 5
   Run readiness checks

   Ping each critical dependency once; only now report ready to the orchestrator (Health Checks).

   fails by Reporting ready before dependencies are reachable sends traffic to a process that cannot serve it, and the load balancer will happily do so.

6. 6
   Start accepting work

   Bind the port, or start consuming the queue. First real request runs through a graph that is already proven.

   fails by Binding first means requests arrive during construction and see half-built objects.

7. 7
   Register shutdown

   Reverse the sequence on signal: stop accepting, drain, close pools (Graceful Shutdown: The 502 Spike Nobody Investigates).

   fails by Whoever built the pool must close it; if construction is scattered, so is teardown, and connections leak on every deploy.

Every step in this list exists because the failure it prevents is one that otherwise happens *after* the deployment is declared successful. That is the whole design goal of a startup sequence: convert late, confusing failures into early, obvious ones.

• If the answer is a container, keep registration in one module. The container's cost is invisibility, and centralised registration buys most of it back (Service Locator).
• Whichever you choose, keep configuration loading out of modules. That decision matters more than manual-versus-container and gets argued about far less.
• A container does not give you dependency direction or inversion. If policy imports the vendor SDK, it still does after you install one (Dependency Inversion, Critically).