Drawing module boundaries

A good boundary confines a likely change behind a small, stable interface. The whole point of a module edge is the change you don’t have to make: callers on the far side keep working because they depend on the interface, not the implementation. So you draw the boundary around the thing most likely to vary — a payment provider, a tax rule, a storage backend — and expose the narrowest surface that callers actually need.

// payments/index.ts — the boundary. Callers see only this.
export interface PaymentGateway {
  charge(amountCents: number, token: string): Promise<ChargeResult>;
}
export type ChargeResult = { ok: true; id: string } | { ok: false; reason: string };

Behind this seam, StripeGateway can become AdyenGateway, retries and idempotency keys can appear, and the checkout code never changes — it only ever knew charge. The interface is small (one method) and stable (it describes what, which rarely moves), while the implementation is large and volatile (it describes how, which moves constantly). That asymmetry — small stable surface, large volatile body — is the signature of a boundary worth having.

Cohesion is the force that decides what lives inside a boundary: things that change together belong together. A module is cohesive when its parts serve one purpose and change for one reason. The operational test is the one from the change-cost lens: when a single requirement moves, how many modules do you open? One means the cohesion matched the change. Many means the boundary was drawn across the change instead of around it.

// HIGH cohesion: everything a "checkout" needs, in one place
checkout/
  checkout.handler.ts    // HTTP in/out for checkout
  pricing.ts             // the checkout pricing rule
  checkout.repo.ts       // checkout persistence
  checkout.types.ts      // shapes shared only inside checkout

Adding a checkout coupon is one directory of edits. The pieces are coupled to each other — but that’s fine: they were always going to change together, so internal coupling is just the module doing its job. The error is confusing this benign within-module coupling with the harmful kind across modules.

Coupling has a direction, and the direction is the whole game: afferent vs efferent. Afferent coupling (Ca) counts who depends on a module — its incoming arrows, its fan-in. Efferent coupling (Ce) counts whom the module depends on — its outgoing arrows, its fan-out. The ratio gives instability: I = Ce / (Ca + Ce), from 0 (nothing I depend on; everyone depends on me — maximally stable) to 1 (I depend on everything; nobody depends on me — maximally unstable).

// A leaf detail: high Ce, low Ca → I ≈ 1 (unstable, free to change)
//   StripeGateway depends on the Stripe SDK, config, logging, the PaymentGateway interface
//   …and (almost) nothing depends on StripeGateway directly.

// A core abstraction: low Ce, high Ca → I ≈ 0 (stable, expensive to change)
//   PaymentGateway depends on nothing; checkout, refunds, invoicing all depend on it.

Stability here is not “good code” — it’s a statement about blast radius. A module that many things depend on (high Ca, low I) is expensive to change because the change ripples outward, so it had better be an abstraction that rarely needs to. A module nothing depends on (low Ca, high I) is cheap to change because nothing breaks downstream — which is exactly where you want volatile detail to sit.

Stable-Dependencies Principle: depend in the direction of increasing stability. Arrows should point from the unstable toward the stable — I should decrease along every dependency edge. Volatile detail depends on stable abstraction; never the reverse. The reason is mechanical: if a stable module depended on a volatile one, every twitch of the volatile detail would force a change in the thing everyone else depends on, and the ripple would tear through the system. Pointing the arrow the other way means volatility stays trapped in the leaves where its blast radius is zero.

// RIGHT: detail → abstraction. Instability decreases along the arrow.
//   checkout (I≈0.6)  →  PaymentGateway (I≈0.0)  ←  StripeGateway (I≈1.0)
//   Both the policy and the detail depend on the stable interface in the middle.

// WRONG: abstraction → detail. checkout imports StripeGateway directly.
//   import { StripeGateway } from "../payments/stripe";   // a stable caller now married to a volatile detail

The right-hand shape is just Dependency Inversion stated as a boundary law: the volatile StripeGateway and the volatile checkout policy both point inward at the stable PaymentGateway. When the failure mode appears — a stable module reaching out to a concrete, fast-moving one — you’ve planted a dependency that runs uphill against stability, and it will be the source that breaks far more than it should.

Package by feature, not by layer — and recognise package-by-layer as high coupling disguised as organisation. Package-by-layer groups files by technical kind: controllers/, services/, repositories/. It looks orderly because every file of a kind is together. But requirements don’t arrive by layer — they arrive by feature. “Add gift cards” is one change request that, under a layer split, forces edits in controllers/, services/, repositories/, and dto/ simultaneously: shotgun surgery, every time. The folders are cohesive by the wrong axis (kind), which means they are coupled along the axis that actually varies (feature).

package-by-layer  (low cohesion per feature)     package-by-feature (high cohesion per feature)
  controllers/  checkout.ctrl, refund.ctrl          checkout/   handler, pricing, repo, types
  services/     checkout.svc, refund.svc            refunds/    handler, policy, repo, types
  repositories/ checkout.repo, refund.repo          payments/   gateway (boundary), stripe, adyen
  one feature = one edit in every folder            one feature = one folder

Package-by-feature isn’t a style preference; it aligns the boundary with the change axis, so the common change is local and the cross-module surface shrinks to deliberate, stable seams (like payments/). When not to apply it: a genuinely cross-cutting concern with no feature home — auth middleware, a logging adapter, shared value types — does belong in a shared/platform module. Forcing those into a feature folder just relocates the coupling. Feature-first, with a small honest “shared kernel” for what truly spans features.