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]>
54 lines
3.6 KiB
Markdown
54 lines
3.6 KiB
Markdown
# Ekklesia module template
|
|
|
|
This is the smallest supported backend-only Ekklesia module. It proves the static manifest,
|
|
compiled runtime and schema entrypoints, capability registration, a module-owned Drizzle table, a
|
|
generated module-owned migration, logical storage-bucket declarations, and one permissioned HTTP
|
|
route (`GET /records`, declared in `register`) that reads that table through
|
|
`context.services.database` — the platform-provided `ModuleDatabase` facade, never a
|
|
module-constructed Drizzle instance or a raw `pg` client. Migration execution and storage
|
|
provisioning are intentionally not included.
|
|
|
|
This template ships backend behavior only, which is a choice rather than a constraint: as of
|
|
[ADR 0021](../../docs/architecture/decisions/0021-modules-as-hostable-products.md) a module may also
|
|
declare an optional compiled `entrypoints.ui` artifact. The template does not, because no host loads
|
|
a UI entrypoint yet — see
|
|
[Declaring a UI entrypoint](../../docs/module-development/README.md#declaring-a-ui-entrypoint) for
|
|
what is and is not supported today.
|
|
|
|
To create a module inside this repository:
|
|
|
|
1. Copy this directory to `modules/<module-id>`.
|
|
2. Rename the package in `package.json` and remove `private` when it is ready for publication.
|
|
3. Update the ID, name, version, namespaces, compatibility ranges, and bucket requests in
|
|
`ekklesia.module.json`.
|
|
4. Keep the manifest capability versions and dependency ranges aligned with the contracts the
|
|
module actually implements and consumes.
|
|
5. Replace `src/server/index.ts` with backend behavior only. Its `defineModuleRuntime` ID and version
|
|
must match the manifest; do not duplicate the rest of the manifest in TypeScript. Declare HTTP
|
|
routes only in `register`, against a permission the manifest already declares; `start`, `stop`,
|
|
and every route handler — never `register` — receive `context.services.database`, a typed
|
|
`ModuleDatabase` view over the platform's one PostgreSQL pool.
|
|
6. Replace the pure Drizzle declarations in `src/schema/tables.ts` and keep its table prefix aligned
|
|
with the module ID. Keep the `defineModuleSchema` ownership wrapper in `src/schema/index.ts`
|
|
aligned too, and never import another module's schema.
|
|
7. Update `drizzle.config.ts`, generate forward migrations with `pnpm migration:generate
|
|
--name=lowercase_name` from the module directory, and review the SQL. Keep each generated tag in
|
|
`drizzle/meta/_ekklesia.json`, classify it as `none` or `approval-required`, and change that
|
|
file's `moduleId` when renaming the template.
|
|
8. Run `pnpm install`, `pnpm build`, `pnpm modules:validate`, `pnpm migrations:validate`, and
|
|
`pnpm verify` from the repository
|
|
root. The declared production entrypoint is the compiled `dist/server/index.js`, not source
|
|
TypeScript; the schema entrypoint is likewise compiled to `dist/schema/index.js`.
|
|
|
|
Do not add UI components, styles, renderers, navigation, or layouts. Those belong to surfaces.
|
|
Keep imports side-effect-free, register capabilities in `register`, acquire resources in `start`,
|
|
and release them in `stop`. Never construct a Drizzle instance, read `DATABASE_URL`, or reach for a
|
|
raw `pg` client — `context.services.database` is the only supported way to query this module's own
|
|
tables, and it is never available during `register`.
|
|
|
|
The migration directory uses the pinned stable Drizzle Kit `0.31.10` PostgreSQL journal and
|
|
snapshot format. Migrations are forward-only and may modify only this module's objects. Offline
|
|
validation treats SQL as opaque bytes, calculates SHA-256 from the exact contents, and never opens a
|
|
database or executes SQL. Destructive declarations are review metadata, not automatic SQL
|
|
classification or approval.
|