ekklesiaandClaude Opus 5
a02deb9433
Phase 6C pass 1. ADR 0024 named the one thing missing between the module UI build pipeline and the generic host loader: Core resolves entrypoints.ui to an absolute server filesystem path, and a browser needs a URL. This adds that publication layer. Core owns the policy. createModuleUiPublicationRegistry builds, from the discovered and started module inventory, the answer to "may this be published, and which exact file is it?" — publishable means the module survived discovery and declares entrypoints.ui, with no new lifecycle state and no installer. apps/api owns the transport: GET /api/v1/module-ui/<module-id>/<version>. Both segments are lookup keys, not path components. An exact match yields the canonical artifact path discovery already validated; no request value is ever composed into a filesystem path, and the route declares no wildcard segment, so traversal, encoded separators, sibling chunks, package-root files, and source maps are unreachable by construction. An installed module directory never becomes a static file root. The prefix is a sibling of /api/v1/modules/, not a child: `ui` is a legal module route segment, so a module registering GET /ui/:version would otherwise compete with the platform for one URL with routing order deciding the winner. The route requires no authentication, deliberately. Fetching the bundle confers no authority, and a cookie-gated route would break cross-origin import(), which sends none. The cost is stated rather than hidden: a caller who knows a module id and its exact version can download that bundle. The three failure modes return one identical 404 so the route is not an enumeration oracle. Caching is no-cache with a strong SHA-256 ETag and RFC 9110 If-None-Match handling, not immutable: without an installer nothing stops a version being rebuilt with different bytes. The server reads bytes and writes bytes — never imports, evaluates, or transforms the artifact. Nothing mounts a module UI. A host could now obtain a URL, which was previously impossible; there is still no Dashboard shell, navigation, or metadata endpoint. Co-Authored-By: Claude Opus 5 <[email protected]>
6.3 KiB
6.3 KiB
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/* |
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 may own UI (ADR 0021) and authors it in
React and TypeScript (ADR 0022). A
module may therefore contain
.tsxsource and depend onreact,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 (includingreact-router-dom,react-native, and@vitejs/plugin-react) or on shared UI-role packages. A module needs no bundler plugin:@ekklesia/module-ui-build— atoolingpackage, a role modules could already depend on — owns the entire module UI build (ADR 0023). 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). @ekklesia/module-ui-sdkhas no dependencies at all, and@ekklesia/module-ui-hostdepends 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). Core owns the policy (createModuleUiPublicationRegistry, built only from already-validatedDiscoveredModulerecords);apps/apiowns the HTTP route and the one canonical URL construction. Neither@ekklesia/module-ui-hostnor@ekklesia/module-ui-sdklearns 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.
- 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.