agentic-dev-template/.claude/skills/improve-codebase-architecture/LANGUAGE.md

Language

Shared vocabulary for every suggestion this skill makes. Use these terms exactly — don't substitute "component," "service" (we use that narrowly for DI ports), "API," or "boundary" (overloaded with our workspace-tag enforcement). Consistent language is the whole point.

This vocabulary is foundational for the skill's reasoning. The project's domain vocabulary lives in docs/glossary.md — terms like use case, manifest, slice, binder, brand, conformance band, coverage layer. Both vocabularies are in scope when proposing deepenings; see the "Mapping to this repo's identifiers" section below for how the abstract terms here land on concrete file shapes.

Terms

Module — in this repo, "module" defaults to "feature" (packages/<name>/). The abstract definition (anything with an interface + implementation) still applies at narrower scales — a use case, controller, repository/service port, or binder can also be a module — but whenever the refactor scope is "the whole thing", say feature. Reach for "module" only when the abstraction across scales actually matters (e.g., comparing how a use case's depth differs from its containing feature's depth). Avoid: unit, component, service (we use "service" for DI ports specifically).

Interface Everything a caller must know to use the module correctly. Includes the type signature, but also invariants, ordering constraints, error modes, required configuration, performance characteristics, manifest declarations, and DI symbol contract. Avoid: API, signature (too narrow — those refer only to the type-level surface).

Implementation What's inside a module — its body of code. Distinct from Adapter: a thing can be a small adapter with a large implementation (a Payload-backed repository) or a large adapter with a small implementation (an in-memory mock). Reach for "adapter" when the seam is the topic; "implementation" otherwise.

Depth Leverage at the interface — the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is deep when a large amount of behaviour sits behind a small interface. A module is shallow when the interface is nearly as complex as the implementation.

Seam (from Michael Feathers) A place where you can alter behaviour without editing in that place. The location at which a module's interface lives. Choosing where to put the seam is its own design decision, distinct from what goes behind it. Avoid: boundary (this repo uses "boundary" specifically for ESLint workspace-tag rules — keep it for that meaning).

Adapter A concrete thing that satisfies an interface at a seam. Describes role (what slot it fills), not substance (what's inside). In this repo every port typically has at least two adapters (real + mock); some have three (real + mock + recording).

Leverage What callers get from depth. More capability per unit of interface they have to learn. One implementation pays back across N call sites and M tests.

Locality What maintainers get from depth. Change, bugs, knowledge, and verification concentrate at one place rather than spreading across callers. Fix once, fixed everywhere.

Principles

• Depth is a property of the interface, not the implementation. A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface.
• The deletion test. Imagine deleting the module. If complexity vanishes, the module wasn't hiding anything (it was a pass-through). If complexity reappears across N callers, the module was earning its keep.
• The interface is the test surface. Callers and tests cross the same seam. If you want to test past the interface, the module is probably the wrong shape.
• One adapter means a hypothetical seam. Two adapters means a real one. Don't introduce a seam unless something actually varies across it. In this repo, the typical justification is "one real adapter + one mock for tests" — that's two.
• The manifest is a structural seam. A feature's feature.manifest.ts declares its use cases / events / jobs / channels / required cores / coverage bands. Refactors that move behaviour between features MUST move manifest entries too; the conformance gates enforce this.

Relationships

• A Module has exactly one Interface (the surface it presents to callers and tests).
• Depth is a property of a Module, measured against its Interface.
• A Seam is where a Module's Interface lives.
• An Adapter sits at a Seam and satisfies the Interface.
• Depth produces Leverage for callers and Locality for maintainers.

Mapping to this repo's identifiers

Abstract → concrete translation table. When proposing a deepening, name things using the right column.

Abstract term	Where it lands in this repo
Module	Primarily a feature (packages/<name>/) — that's the canonical refactor scope. Also: a use case (*.use-case.ts), controller (*.controller.ts), repository port + adapters (*.repository.{interface,mock,}.ts), service port + adapters (*.service.{interface,mock,}.ts), binder (bind-production.ts / bind-dev-seed.ts), manifest (feature.manifest.ts), or a core package (packages/core-<name>/) — when the refactor operates at those narrower scales. When in doubt, say "feature".
Interface	The exported types from a module file: IXUseCase = ReturnType<typeof xUseCase>, IXController, the <x>.repository.interface.ts shape, the manifest's declared keys, the Zod input/output schemas, the DI symbol contract.
Implementation	The factory body, the adapter class body, what the binder wires.
Seam	<x>.repository.interface.ts, <x>.service.interface.ts, the DI symbol (*_SYMBOLS.IXRepository), the manifest entry, a // <gen:*> anchor, the protocol types in core-shared/di/bind-protocols.ts.
Adapter	<x>.repository.ts (Payload real) ↔ <x>.repository.mock.ts (in-memory). For instrumentation: Noop* ↔ Otel* ↔ Recording* (test). For bus: InMemoryEventBus ↔ PayloadJobsEventBus.
Test stand-in	The .mock.ts adapter (constructed directly + injected into the factory). No container rebinding (ADR-012).

Rejected framings

• Depth as ratio of implementation-lines to interface-lines (Ousterhout's original metric): rewards padding the implementation. We use depth-as-leverage instead.
• "Interface" as the TypeScript interface keyword or a class's public methods: too narrow — interface here includes every fact a caller must know, including manifest entries and DI symbols.
• "Boundary" as a synonym for seam: this repo uses "boundary" specifically for ESLint workspace-tag rules (feature may depend on core + tooling only). Keep that meaning intact; say seam or interface when discussing features.
• "Service" as a generic term: in this repo, service = a DI-injected port for non-collection capabilities (IAuthenticationService, IMailerService). Not a generic stand-in for "feature" or "the module doing the work."
• "Module" as the canonical noun: avoid in everyday discourse — say feature (or use case / controller / package when narrower). "Module" is the abstract refactor vocabulary's word for the same thing, useful only when the abstraction across scales is the point.

Cross-references

• docs/glossary.md — project domain vocabulary (use case, manifest, slice, brand, coverage band, etc.)
• docs/decisions/ — 21 ADRs that constrain the design space
• SKILL.md — the skill's process + hard constraints
• DEEPENING.md — dependency categories + seam discipline
• INTERFACE-DESIGN.md — parallel sub-agent design exploration