chore: establish Ekklesia platform foundation

2026-07-12 20:28:19 -05:00
commit 192a6514cf
47 changed files with 2505 additions and 0 deletions
@@ -0,0 +1,40 @@
+# 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.