ekklesiaandClaude Opus 5
44ba259f58
Ekklesia's module model has been backend-only since ADR 0001: a module owns domain behavior and data, and every presentation concern belongs to a surface. That prevents a module author — the person who knows the domain — from shipping the screen that makes their module useful, and it guarantees a module and its own UI drift apart. It also pushes toward two codebases for one domain the moment a module needs to run standalone. ADR 0021 replaces that rule. A module is an independently versioned product that owns its domain behavior, data, permissions, routes, migrations, and its own UI, hostable inside Ekklesia and — from the same implementation — by a later standalone host. Core keeps the containing application shell and every platform policy: authentication, authorization enforcement, platform context, top-level routing, navigation, global theme, error boundaries, and trusted-origin/CORS. The module graph stays flat: modules are peers, genuine module and capability dependencies remain the only relationships, and Dashboard folders are presentation configuration an administrator can reorganize, never module architecture. This pass implements the static contract only. `manifestVersion` moves to 4 and `entrypoints` gains one optional field, `ui`. Version 3's `entrypoints` is strict and rejects `ui`, so this is an incompatible shape change and version 3 is now rejected outright rather than reinterpreted, exactly as version 1 was by version 2 and version 2 by version 3. Every field version 4 adds is optional, so upgrading a backend-only manifest is a one-character edit. Discovery resolves and validates `ui` under the same rules as `server` and `schema` — package-relative, inside the package before and after symlink resolution, a real file, compiled ESM `.js`/`.mjs`, so source TypeScript is rejected rather than assumed to be compiled later. Discovery stays inert: nothing imports, evaluates, mounts, or renders a UI entrypoint, and a test proves a throwing artifact still discovers successfully. This follows `entrypoints.jobs`, declared and resolved since ADR 0006 with no runtime consumer. The name is `ui`, not `dashboard`, because a module's UI must be hostable by Ekklesia's shell and by a standalone host, so the contract cannot be named after one of them; and not `surface`, because `surfaces/*` is a separate ownership layer. No widget, route, icon, folder, menu, layout, or standalone-metadata field is added, and tests assert the manifest still rejects every unknown entrypoint key and offers no hierarchy field. Deliberately unchanged: `scripts/check-boundaries.ts` still enforces `modules-do-not-own-ui`. Relaxing that guard depends entirely on the UI authoring model a later pass chooses, and weakening a working protection before that decision exists would trade real coverage for nothing. A module may therefore declare `ui` today only for a framework-neutral compiled artifact, and the docs say so rather than implying otherwise. Restart-based discovery, explicit operator-invoked migrations, and the trusted compiled-module model are untouched — a module that ships UI is exactly as trusted as one that does not. No Dashboard shell, UI runtime, renderer, framework choice, navigation registry, grouping system, standalone host, installer, hot-loading, or feature module is added by this pass. Co-Authored-By: Claude Opus 5 <[email protected]>
4.4 KiB
4.4 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 (per ADR 0021) the module's own UI | Module SDK, public contracts, 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 cannot contain presentation source, including JSX/TSX, single-file components,
Astro/Marko/MDX/HTML views, stylesheets, or SVG presentation assets, and cannot depend on UI
frameworks or shared UI-role packages. This rule is still enforced, but it is no longer the
architectural direction. ADR 0021 establishes
that a module may own its own UI and declare a compiled
entrypoints.uiartifact. The deny list above stays in force until a later Phase 6 pass chooses the module UI authoring model and decides what replaces it; until then a module UI must be a framework-neutral compiled artifact. Core still owns the containing application shell and all platform policy. - 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 — and revisiting the guard itself is an explicit prerequisite of the module UI authoring pass (ADR 0021).
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.