Package design: names as API, internal/, dependency direction, and the cycle that blocks your hotfix

The package name is the first word of your API

Every exported identifier is read with its package name attached: http.Server, json.Marshal, time.Duration. That makes the package name part of the API, and it drives two rules. First, name packages for what they provide, not what they contain: billing, retry, pdf — a noun describing the capability. Names like models, helpers, types, interfaces, common describe a kind of code, which means everything in the codebase eventually qualifies, which is how a package becomes a gravity well that everyone imports and that imports everyone — the models package in the Hook armed the cycle precisely because both billing and customer needed its types. Second, design identifiers to read with the prefix: http.Server, not http.HTTPServer; billing.Invoice, not billing.BillingInvoice. Stutter is not just cosmetic — it is a sign the author designed the identifier in isolation from the only way callers will ever see it. The test for a healthy package: can you state its purpose in one sentence that is not “miscellaneous things used by several services”? util fails that test by construction, and it fails operationally too: a ninety-one-function grab-bag has the union of all dependencies of all its functions, so importing it for util.Clamp drags in the AWS SDK someone needed for util.UploadJSON.

internal/ and the direction of dependencies

Go gives you exactly one visibility tool above the identifier level: a package under a directory named internal/ can be imported only by code rooted at internal/’s parent. svc/internal/auth is importable by anything under svc/, and by nothing outside it — enforced by the compiler, not by convention or review vigilance. Use it by default: every package starts in internal/ and is promoted out only when an external consumer earns it, because everything outside internal/ in a published module is API you support forever. The deeper discipline internal/ serves is dependency direction. Decide which packages are the core domain (billing, customer — pure logic, importing little) and which are the edges (HTTP handlers, queue consumers, storage adapters), and make every import arrow point from edge to core, never back. A domain package that imports net/http to return a handler-shaped error, or reads a config struct from the transport layer, has reversed an arrow — and reversed arrows are how cycles arm themselves: each one is harmless until a second reversed arrow closes the loop.

Accept interfaces, return structs

Go interfaces are satisfied implicitly, and that one property decides where interfaces should be declared: in the package that consumes them, not the package that implements them. billing needs customer data, so billing declares the two-method CustomerSource it actually needs; the customer package satisfies it without importing billing, without even knowing it exists. Compare the Java-shaped reflex — an interfaces package both sides import — which recreates the gravity-well problem and couples every implementor to a fat, speculative contract. The complementary rule is to return concrete structs: a constructor returning *Client lets you add methods forever without breaking anyone, while returning an interface freezes the method set (every addition breaks third-party implementations) and hides the type’s documentation. Together the two rules keep arrows pointing the right way and contracts minimal:

// Package billing — the consumer declares the contract it needs.
type CustomerSource interface {
	Customer(ctx context.Context, id string) (Customer, error)
}

// Customer is billing's own view: three fields it uses, not customer's 40-field struct.
type Customer struct {
	ID      string
	Country string
	VATID   string
}

func NewInvoicer(src CustomerSource) *Invoicer { // accept the interface…
	return &Invoicer{src: src}                   // …return the concrete struct
}

// Package customer never imports billing. The wiring layer (cmd/serve)
// imports both and adapts: billing.NewInvoicer(customeradapter.New(repo)).

Note the size of the interface: one method. Consumer-side interfaces stay small because they encode one consumer’s needs; provider-side interfaces bloat because they speculate about everyone’s.

Case study: untangling billing ⇄ customer

Back to the Hook’s graph. The repo had models (all shared structs), util (ninety-one functions), and service packages importing both plus each other. The refactor that fixed it ran in four moves, none of which changed behaviour. One: dissolve models — each struct moved to the package that owns its lifecycle (Invoice into billing, Customer into customer); packages that needed another’s data got their own narrow view-struct or a parameter list, because sharing a type is coupling, and most “shared” types were used for two fields. Two: break the cycle with a consumer-side interface — customer’s call into a billing helper became a billing.CustomerSource implementation the wiring layer connects, flipping the arrow’s direction. Three: dissolve util — each function moved next to its only caller (sixty-two of ninety-one had exactly one), genuinely shared ones formed real packages with real names: retry, clock, money. Four: fence the tree with internal/ — everything not consumed by another service moved under it, so the next convenient-but-wrong import became a compile error instead of a review argument. Together, these four moves are a mechanical sequence: dissolve gravity wells, flip one cyclic arrow with an interface, scatter utility functions to their owners, and fence the result. None of them requires a rewrite, and none changes observable behaviour — they only move responsibilities to the packages that should own them. The metric that proved it worked was not elegance: the change amplification dropped — a git log survey showed the median PR before touched 3.4 packages; after, 1.6. Cycle pressure is the smell to act on early: the moment you want an import the compiler refuses, the design is telling you a responsibility lives in the wrong place — the cycle error is the symptom, never the disease.