Skip to content

Module Contracts and Consumer Proof ​

Record the capability before choosing folders or tokens:

QuestionLibrary and school example
Owner and writesAuth validates sessions; Library owns loans; School owns enrollment and capacity
ConsumersLibraryModule and SchoolModule explicitly import AuthModule
Public promiseVerify a credential or fail; return only an immutable id/school principal
Hidden stateSession records and credential details remain inside Auth
Consumer policyA valid identity still needs library or school access; school capacity belongs to School
Duplicate/failure effectsDuplicate enrollment is idempotent; denied/full enrollment leaves state unchanged
CompositionOne exported Symbol aliases VerifySession; private SessionStore is not a module export

The four-axis fixture proves this record with two actual consuming feature modules. Its fixed session map is a teaching adapter, not production authentication. The existing wallet example remains a healthy smaller design; neither requires a repository wrapper for every model.

Prove the right boundary ​

  • Unit checks prove policy with controlled collaborators.
  • A real Nest container proves constructor injection and imports/exports. A global lookup alone does not prove that a consuming module can inject a provider.
  • A shared behavioral suite proves each adapter's stated inputs, outputs, absence/error categories and effects. The inventory suite rejects a type-compatible adapter that returns mutable storage aliases.
  • HTTP checks prove the chosen transport's parsing, status and response projection. They do not prove another transport.
  • Network consumer/provider contracts become useful when independently deployed consumers evolve at different times; they are optional for ordinary local modules.

Keep a healthy case beside the deliberate failure. Here, the shared token resolves; a newly created same-description Symbol does not. A public verification operation resolves; injection of the private session store from another module fails.

Business interactions and dependency graphs ​

Separate business interactions, TypeScript imports, Nest module imports and provider dependencies. A port changes source coupling only when its ownership and binding change the actual edges. It does not automatically remove A → B → A module imports.

If identity disabling must revoke sessions, a real account-lifecycle workflow can depend on both owners instead of adding a reverse identity-to-auth import. Specify atomicity or durable reconciliation before replacing a synchronous operation with events. A successful boot with forward references is not proof of an acyclic graph.

See module-boundaries.md, dependency-injection.md and architecture-review.md. Preserve simple cohesive CRUD and the project's supported conventions.


Canonical source: skills/nestjs-architecture-principles/references/module-contracts.md. This page is generated during the documentation build.

Open-source guidance for deliberate NestJS engineering.

Open-source guidance for deliberate NestJS engineering.

Released under the Apache License 2.0.