41 lines
2.5 KiB
Markdown
41 lines
2.5 KiB
Markdown
# 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.
|