Ekklesia/docs/architecture/decisions/0022-module-ui-authoring-and-host-contract.md

# 0022: Module UI authoring model and host contract

- Status: Accepted
- Date: 2026-08-21
- Extends: [0021](0021-modules-as-hostable-products.md)

## Context

ADR 0021 established that a module is a product which may own its UI, and added `entrypoints.ui` —
a statically validated, never-executed path to a compiled artifact. It deliberately answered none of
the questions that make that field usable, and recorded the gap explicitly: the authoring model was
"the first question the next pass must answer," and `pnpm boundaries` still rejected UI source and UI
framework dependencies inside a module.

Five questions block every later Phase 6 pass:

1. What does a UI artifact export?
2. What does a host give it?
3. How does one artifact run under Ekklesia *and* a standalone host?
4. What is the browser-side trust model?
5. How does module UI avoid being welded to a Dashboard that does not exist?

The repository already leans one way on the first. `packages/typescript-config` ships a `browser.json`
preset (DOM libs, JSX) and a `react-native.json` preset (`"jsx": "react-jsx"`), and ADR 0002 names
"separate Node, browser, and React Native base configurations." No frontend framework is installed
anywhere — the only React or Preact in the tree is inside boundary fixtures that exist to prove the
guard rejects them.

## Decision

### React is the supported module UI authoring model

A module author writes module UI in React and TypeScript (`.tsx`). This is a real choice, not a
neutrality dodge: the repository's own TypeScript presets already anticipate React, Ekklesia's future
first-party UI will be React, and pretending otherwise would push every module author into an
abstraction layer that serves nobody. One framework is supported. Vue, Svelte, Angular, Preact,
Solid, Qwik, Lit, Astro, Marko, and React Native remain unsupported and remain rejected by
`pnpm boundaries`.

**React is the supported authoring model. It is not part of the host contract.** That distinction is
the whole design, and the next section is where it is enforced.

### The host contract is a mount function, not a component

A module's compiled `entrypoints.ui` artifact default-exports a `ModuleUiDefinition`
(`packages/module-ui-sdk`):

```ts
export default defineModuleUi({
  id: "announcements",
  version: "0.1.0",
  mount(container, context) {
    const root = createRoot(container);
    root.render(<Editor context={context} />);
    return () => root.unmount();
  },
});
```

`id` and `version` are build-artifact identity markers, mirroring `ModuleRuntimeDefinition` exactly
(ADR 0006): a host proves the bundle it imported was built from the module it thinks it is, and a
stale artifact is caught rather than mounted. They duplicate nothing else from the manifest.

`mount` receives a container `Element` and the host context, and returns an unmount function or
nothing. A module that acquires anything — a React root, a subscription, a timer, a listener —
returns an unmount and releases it there, exactly as a backend module releases resources in `stop`.

React appears nowhere in that contract. A host needs an element and a context; it does not need to
know, share, or match the module's rendering library. That keeps three things independent that would
otherwise be welded together: the module's framework, the host's framework, and the platform
boundary between them. React can be the supported way to *write* module UI while the *contract*
outlives any particular version of it.

### `@ekklesia/module-ui-sdk` is a separate, browser-safe package

The contract lives in a new shared package with role `module-ui-sdk`, not in `@ekklesia/contracts` or
`@ekklesia/module-sdk`. The reason is concrete rather than organizational: `@ekklesia/module-sdk`
re-exports all of `@ekklesia/contracts`, which pulls Zod, Drizzle, and semver behind one barrel
export. Routing module UI through it would drag a backend dependency graph into a browser bundle.

The package therefore has no runtime dependencies. Its one dependency on `@ekklesia/contracts` is
type-only (`import type { EkklesiaPrincipal }`), erased at build time, so a host and a module UI
provably share Core's principal type without shipping any of Core's runtime.

Both hosts consume this same package. It is not a Dashboard framework and must not become one: no
components, no layout, no design system, no router.

### The host context is deliberately four members

> **Partial correction — see [ADR 0024](0024-browser-safe-ui-sdk-and-host-loader.md).**
> `principal` is no longer typed as Core's `EkklesiaPrincipal`. That import made this package depend
> on `@ekklesia/contracts`, whose barrel pulled Drizzle's types — and Node's globals — into every
> browser program that imported the SDK. The context now uses a browser-owned `ModuleUiPrincipal`
> with the same shape and an unbranded `userId`, and the SDK has no dependencies at all. The four
> members and everything else in this section are unchanged.


```ts
interface ModuleUiHostContext {
  readonly moduleId: string;
  readonly api: ModuleUiApiClient;
  readonly principal: EkklesiaPrincipal;
  readonly permissions: ModuleUiPermissions;
}
```

This is the smallest set that proves the architecture, not the set a finished screen will want.
Navigation, host theme and design tokens, module configuration, organization/platform context, and
diagnostics reporting are **not** included. Each needs a design that does not exist, and a
speculative field frozen into a public contract costs more to remove than to add later. A host passes
this object and nothing else; there is no platform singleton, no global, and no escape hatch to Core.

### Module UI addresses its own API relatively, never by URL

`ModuleUiApiClient.request(path, init)` takes a path **relative to the module's own API root** and
returns a `Response`. The module asks for `posts`. The host decides what that means.

This is the single most important portability rule here. Ekklesia mounts module routes under
`/api/v1/modules/<module-id>` (`apps/api/src/module-http-routes.ts`), but that prefix is Ekklesia's
private deployment detail. A standalone host serving one module may expose the same routes at `/api`,
at another origin, or behind a proxy. A module UI that builds
`/api/v1/modules/announcements/posts` itself is silently welded to Ekklesia and can never be hosted
anywhere else — and the failure is invisible until someone tries.

`Request`/`Response` are the same Fetch vocabulary a module's backend routes already speak (ADR
0015), so one module speaks one HTTP shape on both sides of the wire. Credentials, base URL, and any
platform headers are the host's responsibility; a module UI neither supplies nor sees a session
token. No backend routing changed in this pass.

### Module UI is trusted first-party code in the host's realm

Module UI runs in the same browser JavaScript realm as the host shell. There is no iframe, no
sandbox, no cross-origin isolation, and no capability confinement. A module's UI can reach the host
page, the DOM, `window`, and any global the browser exposes, exactly like any other script the
application loads.

**This is a trusted-code model, stated plainly rather than dressed up.** It matches, and does not
extend, the backend model ADR 0021 preserved: installing a module already means running its code in
the API process with the API's PostgreSQL authority. A module whose server code is trusted with the
database is not meaningfully constrained by sandboxing its browser code.

Introducing an iframe or a separate origin now would add real cost — postMessage plumbing, styling
seams, focus and accessibility breakage — to buy theoretical separation from code that already has
server-side authority. That trade only becomes worthwhile for genuinely untrusted third-party
modules, which this platform does not accept (see
[Security model and deployment trust boundaries](../../development/security.md)). Nothing in this
contract prevents a future sandboxed tier: a host that wanted one could implement `mount` against an
isolated realm without changing this interface, because the contract is a mount function and a
plain-data context rather than shared object graphs.

### Client-side permission checks are presentation, never enforcement

`ModuleUiPermissions.has(permissionId)` tells a module UI what the host believes, so it can hide an
action, disable a control, or pick an empty state. It is not a security boundary and must never be
described as one.

Server-side authorization remains the only authority. Every module route is enforced by Core's
`requirePermission` middleware against the composed platform permission registry (ADR 0013/0014),
and that enforcement neither knows nor cares what a browser decided. A module UI that consults
`has()` and then calls its API is still fully authorized server-side; one that skips the check and
calls anyway is still denied. The value is that a user does not see a button that would fail.

`permissionId` is a plain `string`, not Core's branded `PermissionId`, deliberately: branding would
force a module UI to run Zod in the browser to produce a value for a call that decides nothing
security-relevant. The branded type remains the server-side type, where it matters.

### Discovery still never executes UI, and Core still never loads it

`parseModuleUiExport(namespace, expected)` validates an already-imported module namespace. It does
not import anything. Each host performs its own dynamic import — a browser host from a served URL, a
test host from a file URL — and passes the resulting namespace in.

That keeps this package free of any loader, bundler, or URL assumption, and it keeps Core out of the
business of evaluating browser code entirely. Module discovery continues to resolve and validate the
`entrypoints.ui` path and never execute it (ADR 0021), and this pass adds no UI loading to
`core/`, to `apps/api`, or to any startup path. Nothing about restart-based discovery changed, and
nothing about explicit operator-invoked migrations changed.

### Dashboard organization stays outside this contract

The contract carries no navigation entry, route, title, icon, folder, group, or ordering field, and
none may be added as a hierarchy mechanism. ADR 0021 established that Dashboard grouping is
presentation configuration an administrator reorganizes, never module architecture; adding any of it
here would quietly reverse that, because a field in the UI contract is a field a module owns.

### The boundary guard is narrowed precisely, not removed

`pnpm boundaries` keeps enforcing `modules-do-not-own-ui`. Exactly three things changed:

- `.tsx` is no longer a rejected source extension. `.jsx` stays rejected (this repository is
  strict-TypeScript throughout) and `.css` stays rejected (module styling and the module UI build
  pipeline are not designed yet, and a stylesheet would imply a bundling contract that does not
  exist).
- `react` and `react-dom` are no longer rejected dependencies. Every other framework stays rejected,
  including `react-router-dom` (routing belongs to the host), `react-native` (this pass supports
  React on the DOM only), and `@vitejs/plugin-react` (the build pipeline is undesigned).
- Modules may depend on the new `module-ui-sdk` shared role, which itself may depend only on
  `@ekklesia/contracts`.

Layer rules are untouched. Module UI source is subject to the identical import boundaries as module
backend source: it cannot import Core, an app, a surface, a builder, another module, or a shared
package outside the roles a module is allowed. An unsupported framework aliased behind an allowed
name (`"react": "npm:vue@3"`) is resolved and rejected by target, so permitting React did not create
a way to smuggle anything else in.

## Alternatives

- **A React component as the export** (`export default function Ui(props)`). Rejected: it would put
  React into the platform contract, force every host — including standalone — onto the same React
  major, and make a framework upgrade a breaking change to the module boundary. A mount function
  costs a module author three lines and buys independence for all three parties.
- **Web Components as the authoring model.** Rejected as the *authoring* model: it would mean every
  module author writes to a lower-level API than the one Ekklesia's own UI will use, and styling,
  form handling, and state would all need re-solving per module. Notably, the mount contract does not
  forbid a module from using them internally — it only declines to require them.
- **A serialized UI description** (`{"type": "form", "fields": [...]}`) rendered by the host.
  Rejected outright. It is a frontend framework in disguise, it can only ever express what its schema
  anticipated, and the Announcements editor that motivated ADR 0021 is exactly the kind of screen
  such a system cannot express. Ekklesia is not building its own frontend framework.
- **Putting the contract in `@ekklesia/module-sdk`.** Rejected: that package re-exports all of
  `@ekklesia/contracts`, so a module UI bundle would pull Zod, Drizzle, and semver into the browser.
- **Passing a single platform object** (`context.platform`, `context.core`, a store). Rejected: it
  makes every internal a de facto public API, and nothing that reaches a module can be changed
  afterwards without breaking one. Four narrow members can grow; a platform object can only leak.
- **An absolute API base URL** (`context.apiBaseUrl`) instead of a request function. Rejected: a
  module that concatenates a base URL still assumes a path shape underneath it, and it puts URL
  construction — and therefore credential and header policy — back inside the module.
- **Iframe or cross-origin sandboxing now.** Rejected as premature and misleading: real cost today,
  no real containment for code whose backend half already holds the API's database authority, and a
  sandbox claim this repository would not be able to substantiate.
- **Waiting for the Dashboard before defining the contract.** Rejected: the Dashboard would then
  define the contract by accident, and every Ekklesia-specific assumption it happened to make would
  become the standalone host's problem later.
- **Allowing `.css` in modules now.** Rejected: it implies a bundling and style-isolation contract
  that this pass does not design. Deferred deliberately rather than half-answered.

## Consequences

> **Cross-reference — see [ADR 0023](0023-module-ui-build-pipeline.md).**
> The gap this section records — that module UI was not buildable end to end, because no pipeline
> turned `.tsx` into the compiled `entrypoints.ui` artifact — is now closed. ADR 0023 selects
> esbuild, bundles React rather than externalizing it (preserving this ADR's mount-function ABI),
> emits browser ESM at the manifest-declared path, and keeps stylesheet imports unsupported by
> failing the build on one. Everything else in this ADR remains accepted and unchanged.


A module author can now write a real screen in React, against a documented four-member host context,
and know exactly what the artifact must export. Two hosts can consume that artifact with no shared
code beyond one small package, and the test suite proves it by mounting one fixture artifact under
two hosts whose URL shapes and origins differ.

The cost is that this is still a contract without a production consumer. No Dashboard mounts a module
UI, no module ships one, and the build pipeline that turns a module's `.tsx` into the compiled
`entrypoints.ui` artifact is not designed — `browser.json` uses `"jsx": "preserve"`, which needs a
bundler that no module has, and `@vitejs/plugin-react` remains denied. Choosing between a `tsc`-only
JSX preset and a real bundler, together with the styling question, is the next pass's work and is the
reason `.css` stays rejected today.

A second cost is deliberate duplication of effort in the browser: if both the host and a module
bundle React, a page can load React twice. Sharing one copy through peer dependencies, bundler
externals, or an import map is a build-pipeline optimization, not a contract change, and the mount
contract is unaffected by whichever is chosen.

## Deferred

Not implemented, designed, or promised here: the Dashboard application shell, homepage, or
navigation UI; module navigation registration; Dashboard folders, groups, or drag-and-drop
organization; a design system, component library, or theme/design-token contract; the module UI build
and styling pipeline; a standalone application host; a module installer, marketplace, or manager;
hot-loading or runtime unloading; automatic migrations; sandboxed or untrusted module tiers; and
every real feature module. `entrypoints.jobs` still accepts source TypeScript where other executable
entrypoints require compiled output — that inconsistency is unchanged and remains open, because this
pass did not centralize executable-entrypoint validation and fixing it here would have been unrelated
scope.

> **Correction — this deferred item is closed.** `entrypoints.jobs` now requires a compiled `.js` or
> `.mjs` artifact, exactly like `server`, `schema`, and `ui`. Module discovery expresses the rule as
> "every entrypoint except the directory entrypoint (`migrations`)", so the omission that let `jobs`
> escape it cannot recur. No jobs runtime was added: the entrypoint is still declared, validated, and
> never executed. Every other item in this list remains deferred.