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]>
2.0 KiB
0001: Four-layer platform boundary
- Status: Accepted
- Date: 2026-07-12
Context
Ekklesia must remain understandable and independently extensible after many backend capabilities and user experiences have been added. A conventional feature monolith or UI-bearing plugin model would couple business behavior to a particular presentation framework.
Decision
Partial correction — see ADR 0021. The rule below that a module exposes "data and behavior only" and that "every renderer and UI concern belongs to a surface" was superseded by ADR 0021: a module may own its own UI and ship it as part of an independently versioned product, hostable by Ekklesia and, later, by a standalone host. The four ownership layers themselves, Core's feature-agnostic role, the prohibition on Core importing a module, and every other boundary in this ADR remain accepted and unchanged — Core still owns the containing application shell and all platform policy. This section is left as originally accepted, as the historical record.
Adopt four explicit ownership layers: Core orchestration, backend Modules, presentation Surfaces, and declarative Surface Builder configuration. Begin as a modular monolith. Modules expose data and behavior only; every renderer and UI concern belongs to a surface.
Alternatives
- A conventional feature monolith was rejected because boundaries degrade as features grow.
- UI-bearing plugins were rejected because they bind capabilities to frameworks and visual design.
- Initial microservices were rejected because distribution adds failure modes before contracts have been proven.
Consequences
Stable contracts, SDK ports, generated composition, and automated boundary checks are required. Some integrations take more deliberate service or event design, but modules and surfaces remain independently replaceable.
Migration implications
Future boundary violations must move behind public contracts before the affected package can be treated as independently installable or upgradeable.