ekklesiaandClaude Opus 5
8d651c427d
ADR 0021 established that a module may own UI and added a statically
validated, never-executed `entrypoints.ui` path, but deliberately left
five questions open: what the artifact exports, what a host provides,
how one artifact runs under both Ekklesia and a standalone host, what
the browser-side trust model is, and how module UI avoids being welded
to a Dashboard that does not exist. This answers them.
React and TypeScript are the supported module UI authoring model. The
repository already leaned this way: `packages/typescript-config` ships a
`browser.json` preset and a `react-native.json` preset with
`"jsx": "react-jsx"`, and ADR 0002 names browser and React Native
configurations. One framework is supported; every other stays rejected.
React is deliberately not part of the contract. A module's compiled
artifact default-exports `defineModuleUi({ id, version, mount })`, and
`mount(container, context)` takes a DOM element and returns an unmount
function. `id` and `version` are build-artifact identity markers a host
verifies against the manifest, mirroring `defineModuleRuntime` exactly.
A host needs an element and a context, never a matching rendering
library, so a module's framework, a host's framework, and the platform
boundary between them stay independent.
The contract lives in a new `@ekklesia/module-ui-sdk` rather than in
`@ekklesia/module-sdk`, for a concrete reason: that package re-exports
all of `@ekklesia/contracts`, so routing module UI through it would drag
Zod, Drizzle, and semver into every browser bundle. The new package has
no runtime dependencies, and its one dependency on contracts is
type-only — the emitted `host-context.js` is `export {};`, and a test
pins that so it cannot regress.
The host context is four members: `moduleId`, `api`, `principal`, and
`permissions`. Navigation, theme, module configuration, organization
context, and diagnostics are deliberately absent; each needs a design
that does not exist. Module UI reaches its backend through
`api.request(path)` with a path relative to its own API root and never
constructs `/api/v1/modules/<id>/...`, which is Ekklesia's private
deployment detail — a module that builds that URL is silently unhostable
anywhere else. One fixture artifact is mounted under two hosts with
different origins and URL shapes to prove it.
Client-side permission hints are presentation only, and both the docs
and a test say so plainly: a denied hint does not stop the module from
calling its API, because server-side `requirePermission` is the only
authority. Module UI is trusted code in the host's own browser realm —
no iframe, no sandbox — which matches the backend model rather than
overstating it, since a module's server half already holds the API's
database authority.
The boundary guard is narrowed precisely, not removed: `.tsx`, `react`,
and `react-dom` are un-denied and modules may depend on the new
`module-ui-sdk` role. `.jsx`, `.css`, every other framework,
`react-router-dom`, `react-native`, and `@vitejs/plugin-react` stay
denied, layer rules are untouched, and an unsupported framework aliased
behind an allowed name (`"react": "npm:vue@3"`) is resolved and rejected
by its real target. Fixtures prove each case, including that module UI
source still cannot import Core.
Core, apps/api, and the manifest contract are untouched. Discovery still
validates the `entrypoints.ui` path and never evaluates it; hosts
perform their own dynamic import and validate the result with
`parseModuleUiExport`. No Dashboard shell, UI runtime, navigation,
grouping, standalone host, build or styling pipeline, installer,
hot-loading, or feature module is added.
Co-Authored-By: Claude Opus 5 <[email protected]>
4.7 KiB
4.7 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. 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. Core still owns the containing
application shell and all platform policy, and module UI reaches the host only through
@ekklesia/module-ui-sdk. - 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.