# 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/*` | Backend domain capability and data | Module SDK, public contracts, 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 cannot contain `.tsx`, `.jsx`, `.css`, `.scss`, `.less`, `.vue`, or `.svelte` source
  and cannot depend on a UI framework. Modules expose data and behavior only.
- 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.
- 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.

The boundary test suite includes intentionally invalid fixture graphs. This proves that the guard
rejects forbidden dependency directions even before production packages fill every directory.

## Generated code

Generated artifacts are reproducible outputs with a named generator and validation step. A
generated module bootstrap may import discovered module entry points at an application
composition edge, but Core itself remains feature-agnostic. Generated files are never an excuse
for a hand-maintained central module registry.