ekklesiaandClaude Opus 5
bd34c9c714
Phase 6D pass 1. The shell's navigation was a flat list of module ids, which is not a usable experience — and the obvious fix carries an obvious trap. Letting a module declare its folder, or modelling "Media" as something Livestream and Video belong to, turns a rendering preference into architecture: a folder becomes an owner, membership starts to look like a dependency, and the flat module graph acquires a hierarchy nobody decided on. So the rule comes first: a Dashboard group is a label on a rendering bucket. No manifest, no version, no artifact, no API, no lifecycle; nothing depends on it. Livestream depends on Video because it calls Video's functionality, and that orders startup. Livestream is shown under Media, and that orders nothing. No parent module, child module, owning module, or group-derived dependency appears anywhere in the contracts. No manifest change and no version 5. `manifest.name` has been required since version 1 and already is the module's product identity, so the shell renders "Livestream" instead of `livestream` with nothing added. `suggestedGroup` is deliberately deferred rather than shipped: it would force a hard manifest-version cutover for a hint, and its only correct semantics needs initialization logic that risks a suggestion overwriting an administrator's decision. Defaulting and ownership are different things. Two Core tables (migration 0003) hold groups and placements — server-side, because a church configures its Dashboard rather than one browser; platform-global, because no organization model exists to scope them to. `group_id` is `on delete set null`, so deleting a group ungroups its modules and a dangling reference is impossible. `module_id` carries no foreign key, because modules are packages rather than rows, so a placement for an uninstalled module is retained and restores its position on reinstall. `resolveDashboardNavigation` is a pure function of configuration plus the mountable set: an unplaced module is ungrouped and visible with no initialization write, an absent module renders nothing, empty groups are kept, and ordering is total with the module id as final tie-break. `GET /api/v1/dashboard/navigation` returns the resolved view, layered on top of the host-neutral module UI inventory rather than merged into it — each generic descriptor is embedded untouched, so a standalone host never inherits Dashboard semantics. Reading needs the permission the inventory already needs; organizing needs the new platform permission `core.dashboard.navigation.manage` through a narrow, idempotent, closed-validation mutation contract. No editor UI. The flatness rule is executable: a test discovers real fixtures with a genuine dependency, arranges them four ways including both in one folder and the dependency inverted in presentation, and asserts discovery order, dependency declarations, and the module set stay byte-identical. The end-to-end test organizes a real installation through the real API, mounts a module from inside a group, moves it, and asserts the navigation entry is byte-identical across the move and still mounts the same artifact. The shell's client for the generic inventory became dead code and was removed rather than kept speculatively; the endpoint itself is unchanged. Co-Authored-By: Claude Opus 5 <[email protected]>
106 lines
8.1 KiB
Markdown
106 lines
8.1 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/*` | Domain capability, data, and the module's own UI | Module SDK, module UI SDK, public contracts, React, and external backend libraries |
|
|
| `surfaces/*` | The application shell, UI, renderers, navigation, and interaction | Surface SDK, API/auth clients, the module UI SDK and host loader, design packages, and a browser framework |
|
|
| `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. A module needs no bundler plugin: `@ekklesia/module-ui-build` — a `tooling` package,
|
|
a role modules could already depend on — owns the entire module UI build
|
|
([ADR 0023](decisions/0023-module-ui-build-pipeline.md)). 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. It also may not import
|
|
`@ekklesia/module-ui-host`: that package is host infrastructure, and a module bundling the loader
|
|
would blur the author/host split ([ADR 0024](decisions/0024-browser-safe-ui-sdk-and-host-loader.md)).
|
|
- `@ekklesia/module-ui-sdk` has no dependencies at all, and `@ekklesia/module-ui-host` depends only
|
|
on it. Both are browser-safe by construction: neither can pull a backend type graph — and with it
|
|
Node's global declarations — into browser code. Core still owns the containing
|
|
application shell and all platform policy, and module UI reaches the host only through
|
|
`@ekklesia/module-ui-sdk`.
|
|
- Module UI **asset publication** runs Core → `apps/api`, never the other way
|
|
([ADR 0025](decisions/0025-trusted-module-ui-asset-publication.md)). Core owns the policy
|
|
(`createModuleUiPublicationRegistry`, built only from already-validated `DiscoveredModule`
|
|
records); `apps/api` owns the HTTP route and the one canonical URL construction. Neither
|
|
`@ekklesia/module-ui-host` nor `@ekklesia/module-ui-sdk` learns anything about how Ekklesia
|
|
publishes artifacts — the loader takes a URL and stays host-neutral — and no module may reach
|
|
publication internals. This introduced no new package and no boundary relaxation: `apps/*` could
|
|
already depend on Core and on shared packages.
|
|
- A publication helper accepts module **identity** only. Neither Core's registry nor the API's URL
|
|
builder takes a filename, relative path, or any other artifact selector, so no caller can use one
|
|
to reach a second file inside a module package.
|
|
- A surface never imports Core or a feature module. It uses public API/client contracts, and reaches
|
|
the server over HTTP.
|
|
- A surface may depend only on browser-safe shared roles (`api-client`, `auth-client`,
|
|
`design-tokens`, `module-ui-host`, `module-ui-sdk`, `surface-sdk`, `ui`) plus dev-time `testing`
|
|
and `tooling`. **`@ekklesia/contracts` is deliberately excluded**, despite being a "public
|
|
contract" package: its barrel pulls Drizzle's types, and with them Node's global declarations, into
|
|
any program that imports it — measured in
|
|
[ADR 0024](decisions/0024-browser-safe-ui-sdk-and-host-loader.md), which removed exactly that
|
|
import from `@ekklesia/module-ui-sdk` to close the browser boundary. `module-sdk` re-exports the
|
|
same barrel and is excluded for the same reason. A surface declares its own types for the wire and
|
|
validates what arrives ([ADR 0026](decisions/0026-minimal-ekklesia-module-ui-host.md)).
|
|
- Dashboard navigation configuration is **Core-owned platform state**, never module-owned: Core
|
|
stores groups and placements and resolves the view, `apps/api` exposes it, and `surfaces/shell`
|
|
renders it. A group is presentation configuration and never module structure — it has no manifest,
|
|
version, artifact, or lifecycle, and nothing in discovery, dependency resolution, or module startup
|
|
may ever read it
|
|
([ADR 0027](decisions/0027-dashboard-navigation-and-flat-modules.md)). A module's manifest declares
|
|
its own display name and nothing about where it is presented.
|
|
- The browser host (`surfaces/shell`) statically imports no module. Every installed module UI it can
|
|
mount arrives at run time as a URL from the module UI inventory, is fetched by the generic loader,
|
|
and is never bundled into the shell. Its own build (esbuild, owned by that package) is a separate
|
|
concern from `@ekklesia/module-ui-build`, which compiles a *module's* declared artifact.
|
|
- 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.
|