ekklesiaandClaude Opus 5
e03d38fcab
Modules have owned their own UI since ADR 0021, but the platform has never said what that UI should look like. Every screen here — the Dashboard shell, the display host, the module template — invented its own hex colours, font stack, spacing, and radii, and they already disagreed. A module author had no vocabulary for "the ordinary panel background", so the only available answer was to invent one, and two modules would invent two. Add `@ekklesia/design-tokens`: one validated, enumerable registry of semantic tokens. A token declares a name, label, description, and default value; its category and `--ekklesia-*` identifier are derived from the name, so it can never claim one category while being named for another. Construction rejects duplicates, malformed names, unknown categories, empty or overlong text, and any value that is not a bounded literal — no declaration terminator, rule block, comment, at-rule, `url(`, `!important`, escape, control character, or markup. A registry that constructs can therefore be emitted as CSS without escaping, because nothing needing escaping can be in it. That validation is also what makes a future theme editor implementable rather than aspirational. Add `@ekklesia/ui`: button, icon button, text input, select, checkbox, field wrapper, panel, dialog, tabs, table and list primitives, badge, toast, and empty/error/loading states — every value a token reference, with real `:focus-visible` treatment and status that never depends on colour alone. Deliberately small: an element earns its place when two consumers need it. The stylesheet is a string rather than a `.css` file so the identical bytes install into a document or an isolated artifact root, and so hover, disabled, and focus-visible are real CSS rather than JavaScript approximations of them. `pnpm boundaries` opens exactly two shared roles to modules, by name — every other role stays rejected — and pins both design packages to the bottom of the presentation stack. Both are browser-safe by construction, proven by a real compile of module-shaped source in which `process.env` must fail to typecheck. The shell installs the defaults at its document root for the Dashboard and the display; custom properties inherit into module artifacts, so a module reads `var(--ekklesia-…)` with nothing to import at run time and nothing for a host to forget to pass. Co-Authored-By: Claude Opus 5 <[email protected]>
11 KiB
11 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, the approved design packages, 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) 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 any shared role beyond the two approved design packages named below. 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). - A module may consume exactly two shared design roles:
design-tokens(@ekklesia/design-tokens) andui(@ekklesia/ui), added by ADR 0039. This is a named allowlist, not a general "browser-safe shared packages are fine" relaxation:api-client,auth-client,surface-sdk, andmodule-ui-hostremain rejected inside a module. Both approved packages are browser-safe by construction —design-tokenshas no dependencies at all anduidepends only on it — so a module UI file that imports them still cannot typecheckprocess.env, proven by a real compile under the exact browser project a module uses. Both are also pinned at the bottom of the presentation stack bydesign-packages-depend-downward-only: neither may reach an implementation layer, an API/auth client, or the backend contracts barrel, because a design package that could would put all of it inside every module artifact that renders a button. - A module references registered global semantic tokens and may derive private,
differently-prefixed aliases from them inside its own artifact. It may never define an
--ekklesia-*custom property: that would invent a global theme variable outside the registry, which a future theme editor could not enumerate and another module could unknowingly depend on. @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.- Manifest v6 permits independently optional primary (
entrypoints.ui) and full-viewport display (entrypoints.display) artifacts. Modules own both feature experiences; surfaces own their containers, routes, navigation/chrome, credentials, error states, and publication wiring. The fixed authoring sources aresrc/ui/index.tsxandsrc/display/index.tsx; both use the same role-neutral UI SDK ABI and neither may import a surface or host loader. - 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, 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-timetestingandtooling.@ekklesia/contractsis 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, which removed exactly that import from@ekklesia/module-ui-sdkto close the browser boundary.module-sdkre-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). - Dashboard navigation configuration is Core-owned platform state, never module-owned: Core
stores groups and placements and resolves the view,
apps/apiexposes it, andsurfaces/shellrenders 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). 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. - Dashboard login, logout, and session-transition UX are surface-owned
(ADR 0034). They use the API over HTTP and
must not add credentials, cookies, tokens, or auth methods to
ModuleUiHostContext; modules keep receiving only the host-neutral principal and permission hints already in the UI SDK. - The display browser application is a separate surface entrypoint under
surfaces/shell; it also statically imports no module and mounts only the exact display descriptor/artifact supplied by the API. It contains no Dashboard chrome and does not move display rendering into the surface—the module still owns that renderer. - 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 design packages are covered the same way: one fixture proves a module may depend on both, one proves every other shared role stays rejected, and one proves neither design package may depend upward.
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.