Skip to content

0018. Module boundaries and their automated enforcement

  • Status: Accepted
  • Date: 2026-11-08

Agents work in parallel, and the hexagonal structure of ADR 0008 only holds if wrong imports fail the build. The dashboard must stay a pure API client, and public code must build without cloud/.

Packages (pnpm workspaces, one package per directory):

core/ domain, ports, engine and steps, actions (registry), auth (sole minter of ProjectScope), ingest, tracking, billing, webhooks, extensions
adapters/sql/ shared Kysely repositories, SQLite and Postgres migrations, the DO dialect
adapters/cloudflare/ ProjectDO, WorkspaceBudget DO, rate-limiter DO, D1 ControlStore, Queues, R2, Workers secrets, fetch OutboundHttp
adapters/node-sqlite/ executor, timer, and queue for tests and development
adapters/postgres/ executor (advisory lock and RLS), scheduler poller, jobs table, ControlStore, rate-limiter and budget rows
adapters/aws/ SQS, S3, Secrets Manager
adapters/webcrypto/ Signer, SecretCipher
adapters/email-ses/ adapters/email-fake/
surfaces/http/ Hono app built from the registry: REST and OpenAPI, inbound and provider webhooks, click redirect
surfaces/mcp/ MCP tools built from the registry
surfaces/api-client/ typed client generated from OpenAPI
testing/contracts/ port contract suites
apps/workers/ apps/node/ apps/dashboard/
cloud/ private: extensions and the cloud composition root

Dependency rules:

Package May import
core nothing outside core
adapters/sql core
adapters/cloudflare, adapters/node-sqlite, adapters/postgres core, adapters/sql, adapters/webcrypto
other adapters/* core, adapters/webcrypto
surfaces/http, surfaces/mcp core
surfaces/api-client generated code only
testing/contracts core
tests of adapters/* and apps/* also testing/contracts, as a dev dependency
apps/workers, apps/node core, adapters/*, surfaces/*
apps/dashboard surfaces/api-client and UI libraries only
cloud/ public packages’ exports
  • No adapter imports another adapter except adapters/sql and adapters/webcrypto as listed.
  • cloudflare:* and Workers types only in adapters/cloudflare and apps/workers. node:* and the AWS SDK only in adapters/node-sqlite, adapters/postgres, adapters/aws, and apps/node. Adapters that run on both targets (adapters/email-ses, adapters/webcrypto) use only fetch and WebCrypto.
  • Public code never imports cloud/.
  • Only core/auth mints a ProjectScope.
  • Core does not read time or randomness directly (Date.now, argument-less new Date(), Math.random, crypto.randomUUID); it uses Clock and IdGenerator.

Enforcement:

  • pnpm strict dependencies and package.json exports (no deep imports).
  • TypeScript project references (tsc -b) mirroring the graph; core compiles with types: [] so platform globals fail.
  • dependency-cruiser as the source of truth for the rule table (layer matrix, no public-to-cloud, no adapter-to-adapter, platform modules only where allowed, scope minting only from core/auth, no cycles, no orphans).
  • ESLint no-restricted-syntax in core for the determinism ban.
  • CI: oss-build deletes cloud/, AGENTS.cloud.md, and docs/cloud/ and still builds and tests.
  • The check-dependencies skill explains how to fix a violation by adding a port rather than changing the rule.
  • Changing a rule needs a new ADR and the configuration change in the same pull request.
  • Open: the package for the Node OutboundHttp (undici with a resolver-pinned address check); it needs node:* and is security-critical, so it is placed deliberately when apps/node is built.
  • The earlier proposed layout (core/workflows/, core/email/adapters/) is replaced by core/engine/ and adapters/email-*.

Amendment (2026-11-18, ADR 0040): adapters/auth-better-auth joins the other adapters/* (imports core and adapters/webcrypto; imported by apps/workers and apps/node) and the adapters that run on both targets. Its dependency Better Auth also uses AsyncLocalStorage from node:async_hooks, which both targets provide; its own code imports no node:* or cloudflare:* module. Only it may import better-auth. surfaces/api-client, generated code and a fetch wrapper with no runtime dependencies, also holds a hand-written auth module under the same rule (api-client-no-npm: no npm import, no other package) (ADR 0028 amendment).

Amendment (2026-11-18, ADR 0040 amendment): the tests of adapters/auth-better-auth may import cloudflare:*, because they run on workerd and D1; its src still imports none.

Amendment (2026-11-20, ADR 0051): adapters/auth-better-auth/src/consent-grant.ts imports AsyncLocalStorage from node:async_hooks, which both targets provide, to hand the consent’s grant ID to the plugin; it is the package’s only node:* import.