# Repository boundaries

These rules map platform ownership to filesystem and package boundaries. The executable check is
`pnpm boundaries`; CI must reject violations.

| Area | Owns | May depend on |
| --- | --- | --- |
| `apps/*` | Thin deployable composition roots | Public Core APIs, generated bootstrap, or a surface as required by the app |
| `core` | Feature-agnostic platform implementations | Public contracts and external infrastructure libraries |
| `modules/*` | Domain capability, data, and the module's own UI | Module SDK, module UI SDK, public contracts, React, and external backend libraries |
| `surfaces/*` | UI, renderers, navigation, and interaction | Surface SDK, API/auth clients, public contracts, and design packages |
| `builders/*` | Declarative surface composition tooling | Builder/surface SDKs and public contracts |
| `packages/*` | Explicitly scoped SDKs, contracts, clients, design, testing, or tooling | Only dependencies appropriate to the package's declared level |
| `templates/module` | A small example backend module | The same dependencies allowed for any module |

## Mandatory rules

- Core never imports a feature module, surface, Builder implementation, or app.
- A module never imports Core implementations, another module, a surface, Builder code, or an app.
- A module may own UI ([ADR 0021](decisions/0021-modules-as-hostable-products.md)) and authors it in
  React and TypeScript ([ADR 0022](decisions/0022-module-ui-authoring-and-host-contract.md)). A
  module may therefore contain `.tsx` source and depend on `react`, `react-dom`, and
  `@ekklesia/module-ui-sdk`. It still cannot contain `.jsx`, stylesheets, single-file components,
  Astro/Marko/MDX/HTML views, or SVG presentation assets, and cannot depend on any other UI framework
  (including `react-router-dom`, `react-native`, and `@vitejs/plugin-react`) or on shared UI-role
  packages. An unsupported framework aliased behind an allowed name is resolved and rejected by its
  real target.
- Module UI source is subject to the identical layer rules as module backend source: it may not
  import Core, an app, a surface, a builder, or another module. Core still owns the containing
  application shell and all platform policy, and module UI reaches the host only through
  `@ekklesia/module-ui-sdk`.
- A surface never imports Core or a feature module. It uses public API/client contracts.
- Separate surfaces do not import each other's internals.
- Builder code composes contracts and surface renderer identifiers; it does not import module or
  surface internals.
- Contract and SDK packages cannot depend upward on implementations.
- Workspace package consumers use declared `exports`, not private subpaths.
- Every internal dependency uses a `workspace:` range and every imported workspace package is
  declared by the consumer.
- Workspace aliases are forbidden because they obscure package ownership in the dependency graph.
- Workspace package names are unique and shared packages declare a recognized architectural role.
- Circular source and workspace-package dependencies are rejected.
- Cross-module data access uses services, events, capabilities, or opaque identifiers rather than
  direct table imports and foreign keys. Modules may not import another module's Drizzle tables,
  columns, relations, schema entrypoint, or migration internals.

The boundary test suite includes intentionally invalid fixture graphs. This proves that the guard
rejects every currently machine-checkable repository rule even before production packages fill
every directory. The UI guard rejects component, view, template, stylesheet, shared UI-role, and
common UI-framework dependencies inside modules. This deny list is defense in depth; package
review remains required when adopting a new frontend technology. ADR 0022 narrowed the guard
precisely rather than removing it: React was un-denied, every other framework stayed denied, and the
layer rules were untouched.

The Phase 3 schema validator complements source boundaries by checking table ownership, foreign-key
targets, and physical table namespaces in compiled Drizzle metadata. Offline migration validation
checks each module's packaged Drizzle inventory and policy contract, while deliberately making no
claim that opaque SQL ownership can be proven without PostgreSQL-aware analysis.

## Generated code

Generated artifacts are reproducible outputs with a named generator and validation step. A
generated module bootstrap under the root `generated/` boundary may import discovered module entry
points, and apps may import that generated bootstrap. Handwritten app and Core code still cannot
import feature modules directly. Generated files are never an excuse for a hand-maintained central
module registry.