Lesson 13 · Senior v2 architecture

Composition roots and wiring at the edge

Where concrete dependencies belong, why the wiring code matters, and how to explain the difference between a clean edge and a leaked core.

Your win: explain what a composition root is, why v2 modules want concrete wiring at the edge, and how to review whether a module really preserves that boundary.

In plain English Plain English: the composition root is the place where the abstract architecture meets real concrete things like postgres repos, gRPC servers, and consumer registrations.

The problem: somebody has to build the real objects

Ports and adapters sound clean until you ask a practical question: who actually constructs the postgres repo, the handler, and the controller? The answer is the composition root. If you put that wiring in the wrong place, the dependency arrow starts bending back into the core.

The rule to memorise The core owns interfaces and business flow. The edge owns concrete construction.

What good wiring looks like here

In spike, controller constructors inject concrete repos and handlers. In eureka, `cmd/server/eureka/gserver.go` wires repos into usecases and registers the transport at the outer edge. That is the healthy pattern: the module logic stays focused on behavior, while the outer bootstrapping code owns assembly.

Anchor — where to look in this repo The clean comparison is strongest between eureka and spike on one side, and conversationmgmt's core-side construction leak on the other. The point is not that manual wiring is glamorous; the point is that it keeps the dependency story honest.
Common mistake Thinking a module is still clean because it uses interfaces somewhere, even though the core is also constructing concrete implementations inside itself.
Read this next

Cockburn + repo wiring docs

Read Cockburn's original framing, then compare it with the repo's real wiring conventions in the loaded CLAUDE/rules files.

→ Hexagonal Architecture
→ internal/eureka/CLAUDE.md · internal/spike/CLAUDE.md

Check yourself (from memory)

Q1. The composition root should usually live…

The edge owns assembly; the core owns behavior.
What is the one-sentence rule for the composition root?
recall, then click to reveal
Concrete adapters are wired at the edge so the core can depend only on the ports it owns.
Want me to compare a clean composition root and a leaked one line by line in this repo? Ask me.

Sources. Cockburn; repo CLAUDE docs.