0004. Package boundaries and dependency layering

Design document, published from the repository at docs/adr/0004-package-boundaries.md.

  • Status: Accepted (layer map amended by ADR-0008)
  • Date: 2026-11-13

Context

Without enforced boundaries, monorepos drift into a tangle where everything imports everything, cycles appear and security review loses its footing.

Decision

  • Libraries live in packages/, each with a single responsibility and a single exports entry (see ARCHITECTURE.md §2).
  • An explicit allowed-dependency map (scripts/check-dependency-layers.mjs) defines the layering; deployables may use any library but never each other.
  • dependency-cruiser forbids file-level cycles, cross-package relative imports and production imports of tests.
  • @quantlayer-protocol/sdk is the only package intended for external consumers and must stay browser-safe.
  • Node-specific runtime concerns (logging, health checks, lifecycle) are grouped in @quantlayer-protocol/runtime rather than duplicated in each worker. This package was added beyond the original layout for that reason.
  • packages/database and apps/docs are deferred until they have content.

Consequences

Adding a package requires registering it in the layer map, a deliberate step that forces a decision about its place. Libraries are built before dependants (^build), which Turborepo caches.