Ekklesia/docs/architecture/repository-boundaries.md

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 presentation source, including JSX/TSX, single-file components, Astro/Marko/MDX/HTML views, stylesheets, or SVG presentation assets, and cannot depend on UI frameworks or shared UI-role packages. 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.
• 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.

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.