ekklesiaandClaude Opus 5
1e5866504e
ADR 0022 defined what a module UI is and selected React and TypeScript as the authoring model, but closed by recording that it was not buildable end to end: `browser.json` preserves JSX, bundler plugins are denied, and nothing turned a module's `.tsx` into the artifact its manifest declares. This closes exactly that gap. esbuild produces the artifact. It was already the right answer before it was chosen: this workspace resolves esbuild 0.28.1 through Vite/Vitest today and `pnpm-workspace.yaml` already carries `allowBuilds: esbuild`, so the pinned dependency adds no second copy and no new trust decision. It is also the smallest tool that covers TSX, ESM, browser platform, bundling, source maps, and a define-time constant with no plugin ecosystem. Vite library mode would drag in `@vitejs/plugin-react`, which the module boundary denies on purpose; `tsc` alone cannot bundle, so its output would carry bare `react/jsx-runtime` imports no browser resolves. React is bundled, not externalized. That follows from ADR 0022 rather than from convenience: `mount()` was made the ABI precisely so React would not be part of the host contract, and externalizing it would reverse that through the build system — every host would have to supply a compatible React, and a standalone host might not use React at all. The cost is real and accepted: duplicate runtimes and a ~570 KB unminified artifact. Sharing one runtime later is a build optimization that cannot change the contract, because the contract is a mount function. Output is browser ESM at `es2022`, unminified so an operator can review what they install, with `process.env.NODE_ENV` substituted — React reads it at module scope and would otherwise touch a Node global that does not exist in a browser. The output path is read from the module's own manifest rather than a build convention, so declared and produced artifacts cannot drift, and it is validated with the same `packageRelativePathSchema` discovery enforces, so a build can never write where discovery would later reject. `@ekklesia/module-ui-build` owns every option; modules own none. It uses the existing `tooling` role that modules could already depend on, so this pass required no boundary relaxation at all. Its `bin` points at a committed launcher rather than compiled output because pnpm links bins during install, before Turborepo builds anything — a bin targeting `dist/cli.js` fails to link on a fresh clone and breaks every module's UI build in CI. A module with no `entrypoints.ui` is not an error; the CLI reports nothing to build and exits zero, so one script serves both kinds of module. Styling is React inline style objects. A stylesheet import fails the build rather than emitting a sidecar `.css` that no manifest declares and no host loads — an undeclared asset would appear to work in tests and silently do nothing in a real host. `templates/module` is the canonical example and now ships optional UI. Its tests build the artifact from source, validate it with `parseModuleUiExport`, mount it into a real DOM, assert the rendered output, and unmount it; the artifact is rebuilt per run so the proof can never pass against stale output, and `dist/` stays gitignored. Because verify runs both `pnpm test` and `pnpm build`, a UI that cannot be produced fails CI through two independent paths. One correction worth stating plainly: the UI TypeScript project declares `"types": []`, and a UI file referencing `process` does fail in isolation, but TypeScript still pulls Node globals in transitively — a file importing `@ekklesia/module-ui-sdk` reaches `@ekklesia/contracts` and through its Zod and Drizzle types `process.env` typechecks again. The docs and ADR describe this as the convention it is rather than the guard it is not. Core is untouched. Building is an authoring step; discovery still only validates the artifact a module shipped and never executes or produces one. Co-Authored-By: Claude Opus 5 <[email protected]>
216 lines
14 KiB
Markdown
216 lines
14 KiB
Markdown
# Platform architecture
|
|
|
|
Ekklesia is a long-lived platform from which churches can compose many applications and user
|
|
experiences. It begins as a modular monolith so contracts can stabilize before distribution is
|
|
introduced.
|
|
|
|
> **Trust boundary.** Installed modules are trusted compiled code, not sandboxed plugins: a module
|
|
> runs arbitrary JavaScript in the API process and shares its PostgreSQL role. The layering
|
|
> described below is a correctness and ownership boundary, not hostile-code isolation. A module that
|
|
> ships its own UI ([ADR 0021](decisions/0021-modules-as-hostable-products.md)) is exactly as
|
|
> trusted as one that does not. See
|
|
> [Security model and deployment trust boundaries](../development/security.md).
|
|
|
|
## Dependency model
|
|
|
|
The arrows below mean "depends on." Presentation and composition depend on stable lower-level
|
|
contracts; infrastructure never learns individual feature names.
|
|
|
|
```text
|
|
Surface Builder configuration -> Surfaces -> public capability contracts
|
|
^
|
|
|
|
|
HTTP/API and client contracts
|
|
|
|
|
Feature Modules -> Module SDK / platform contracts <- Core implementations
|
|
```
|
|
|
|
The four ownership layers are:
|
|
|
|
1. **Core** orchestrates generic platform infrastructure: startup, identity, permissions,
|
|
configuration, database connectivity, storage, events, jobs, module discovery, and lifecycle.
|
|
2. **Modules** own domain behavior, data schemas, resources, actions, routes, events, permissions,
|
|
jobs — and, per [ADR 0021](decisions/0021-modules-as-hostable-products.md), their own UI, authored
|
|
in React against `@ekklesia/module-ui-sdk`
|
|
([ADR 0022](decisions/0022-module-ui-authoring-and-host-contract.md)). A module
|
|
is an independently versioned product, not only a backend capability. It does not own the
|
|
containing application shell or any platform policy.
|
|
3. **Surfaces** own the presentation concerns a module does not: the containing application shell,
|
|
layout, navigation, accessibility, interaction, branding, and client state — including the shell
|
|
that hosts a module's own UI.
|
|
4. **Surface Builder** stores validated declarative composition. It selects capabilities and
|
|
surface-owned renderers but contains neither executable code nor module business logic.
|
|
|
|
A module owns its own product experience. Calendar data, actions, permissions, and its own
|
|
management UI live in `modules/calendar`; the dashboard or public-website shell that hosts it —
|
|
navigation, theme, layout, and platform chrome — lives in a surface. The module supplies the screen
|
|
for its feature; the surface supplies the application around it.
|
|
|
|
Modules are flat peers. `video`, `livestream`, `announcements`, and `calendar` are independent
|
|
first-class modules with no parent/child relationship. A Dashboard may group them into folders such
|
|
as `Media` or `Sunday Production`, but those groups are presentation configuration an administrator
|
|
can reorganize, never module ownership and never a dependency. Genuine module and capability
|
|
dependencies remain the only way one module may require another.
|
|
|
|
## Stable seams
|
|
|
|
- Modules use public SDK ports and injected Core services, never undocumented Core internals.
|
|
- Modules do not import another module's schema or private code. Integrations use public service
|
|
contracts, capabilities, events, or APIs.
|
|
- Surfaces consume API/client and capability contracts, never feature-module packages.
|
|
- Core discovers feature modules generically. It contains no feature-specific imports or
|
|
conditional branches.
|
|
- Deployable apps are thin composition roots and do not become domain-logic owners.
|
|
- Generated bootstrap artifacts may connect discovered entry points at the application edge;
|
|
they do not become manually maintained Core registries.
|
|
|
|
## Security invariants
|
|
|
|
- Authorization is enforced server-side.
|
|
- Secrets are isolated from public configuration and logs.
|
|
- Authentication tokens, private form content, prayer requests, and pastoral information are not
|
|
logged.
|
|
- Sensitive actions are designed for auditability without copying sensitive content into audit
|
|
records.
|
|
- Private objects use signed access and namespaced storage paths.
|
|
- Every network service starts from least-privilege and local-only development defaults.
|
|
|
|
## Current implementation status
|
|
|
|
Implemented now: the Phase 1 repository and infrastructure foundation plus public module contracts,
|
|
static versioned manifests, independent capability versions and dependency ranges, automatic
|
|
filesystem discovery, compiled server loading, runtime-definition verification, staged capability
|
|
registration, dependency-ordered startup and reverse shutdown, rollback, and a backend-only module
|
|
template. Optional compiled schema entrypoints now contribute validated, namespaced module-owned
|
|
Drizzle tables to a deterministic aggregate without connecting to a database. Optional module-owned
|
|
Drizzle migration directories now produce an atomic dependency-ordered offline inventory with
|
|
validated metadata, explicit destructive-change declarations, and exact SHA-256 checksums. Core can
|
|
now compare that inventory with its fixed PostgreSQL history table, produce a read-only plan, and
|
|
apply the complete pending batch under a session advisory lock and one transaction. Destructive
|
|
migrations require an exact externally supplied approval bound to module, identity, and checksum.
|
|
Hermetic integration coverage now exercises those contracts through the production adapter against
|
|
the pinned PostgreSQL container, including real DDL rollback and advisory-lock concurrency. The
|
|
Core-owned Doctor composes those existing services into a deterministic terminal readiness report:
|
|
static module, schema, and migration validation always run when their prerequisites succeed, while
|
|
PostgreSQL history planning runs only when configured. Schema inspection evaluates compiled schema
|
|
definition entrypoints, which the module contract requires to be side-effect-free; Doctor never
|
|
imports or starts module server entrypoints. It does not apply migrations or modify PostgreSQL, and
|
|
it honestly skips object storage because no production Core storage service exists yet.
|
|
|
|
Phase 4A added the Core identity foundation. Core owns a Better Auth-backed identity schema
|
|
(`ekklesia_core_user`, `ekklesia_core_session`, `ekklesia_core_account`,
|
|
`ekklesia_core_verification`) reachable only through Ekklesia-owned contracts and an explicit
|
|
Core-owned Better Auth construction boundary; modules never import Better Auth or receive a raw
|
|
database client. That schema ships as a first-class Core-owned migration source that reuses the
|
|
exact migration format, checksum rule, planner, and transactional runner Phase 3 already
|
|
established, ordered before module migrations in the same aggregate. See
|
|
[ADR 0010](decisions/0010-core-identity-and-better-auth-adoption.md).
|
|
|
|
Phase 4B adds identity HTTP transport: a minimal Hono-based `apps/api` composition root mounts
|
|
Better Auth at `/api/auth/*` and exposes one Ekklesia-owned route, `GET /api/v1/principal`, behind
|
|
Core's own Fetch-compatible identity runtime (`@ekklesia/core/identity`) — Core still does not
|
|
depend on Hono. Public email/password registration is the intended eventual product policy — every
|
|
account receives identical lowest-privilege baseline status, and signup order never grants
|
|
elevation — but is disabled by default as of Phase 5D pass 1, below. See
|
|
[ADR 0011](decisions/0011-identity-http-transport-and-public-enrollment.md) and
|
|
[the API guide](../development/api.md), and
|
|
[the identity development guide](../development/identity.md) for the underlying schema and
|
|
contracts. It is now possible to publicly register, sign in, resolve a principal, and sign out.
|
|
|
|
Phase 4C is complete: Core's authorization foundation — a schema, evaluator, and store for
|
|
platform owners, explicit grants, and relationship-derived grants, plus an immutable permission
|
|
registry — and an explicit, single-use, auditable platform-owner bootstrap command, plus reusable
|
|
Hono enforcement and an `/api/v1/grants` HTTP API in `apps/api`. See
|
|
[ADR 0013](decisions/0013-core-authorization-and-owner-bootstrap.md) and
|
|
[the authorization guide](../development/authorization.md).
|
|
|
|
Phase 5A wired module-declared permissions into that same authorization system — a version-3
|
|
manifest, one composed platform permission registry spanning Core's own declarations and every
|
|
installed module's, enforced through the identical middleware Core's own routes use. Phase 5B let a
|
|
module mount its own framework-neutral HTTP routes in production, under
|
|
`/api/v1/modules/<module-id>`, enforced and response-sanitized exactly like Core's own routes. Phase
|
|
5C added typed module database access (`context.services.database`) for a module's lifecycle hooks
|
|
and authorized HTTP handlers, over the platform's one existing PostgreSQL pool.
|
|
See [ADR 0014](decisions/0014-module-permission-declarations-and-platform-registry.md),
|
|
[ADR 0015](decisions/0015-static-module-http-routing-and-runtime-lifecycle.md),
|
|
[ADR 0016](decisions/0016-module-database-access.md), and the repository root
|
|
[README](../../README.md#current-status) for the complete, current status of every phase.
|
|
|
|
**Phase 5D is complete.** Five passes hardened the platform against an independent security audit of
|
|
the Phase 5C checkpoint, and an independent whole-repository re-audit closed the phase:
|
|
|
|
1. the public request perimeter — a server-owned client-address resolution boundary for the
|
|
authentication rate limiter, public sign-up disabled by default behind an explicit typed opt-in,
|
|
an enforced request-body ceiling on every public route (including a module route's own declared
|
|
contract), and finite Node header/request timeouts;
|
|
2. identity session resolution, and a mandatory certificate- **and** hostname-verified PostgreSQL
|
|
transport with no plaintext or `rejectUnauthorized: false` exception;
|
|
3. durable authorization history that survives user deletion, a one-time owner bootstrap that
|
|
deleting a user cannot reopen, and bounded, unambiguous explicit-grant management;
|
|
4. module route-overlap rejection at registration, finite startup rollback and shutdown deadlines,
|
|
and hardened migration command timeouts and SQL execution;
|
|
5. deployment and supply-chain closure plus the final re-audit.
|
|
|
|
See [ADR 0017](decisions/0017-public-request-perimeter-hardening.md),
|
|
[ADR 0018](decisions/0018-identity-session-resolution-and-database-transport.md),
|
|
[ADR 0019](decisions/0019-durable-authorization-history-and-grant-management.md), and
|
|
[ADR 0020](decisions/0020-module-runtime-and-migration-execution-hardening.md).
|
|
|
|
These guarantees hold under a **trusted-contributor, not-yet-deployed** threat model. The remaining
|
|
limitations are operational rather than architectural: CI is a trusted-code-only boundary whose
|
|
runner topology and job-token authority are unverified, and Ekklesia is not deployed, so the origin,
|
|
proxy, and throttling properties a public launch requires are unproven. Neither set of requirements
|
|
blocks Phase 6. Read
|
|
[Security model and deployment trust boundaries](../development/security.md) for what each boundary
|
|
does and does not protect against, and the repository root
|
|
[README](../../README.md#current-status) for the current status of every phase.
|
|
|
|
**Phase 6A established the module product contract.**
|
|
[ADR 0021](decisions/0021-modules-as-hostable-products.md) replaces the backend-only module model:
|
|
a module is an independently versioned product that may own its own UI, hostable inside Ekklesia and
|
|
— later, from the same implementation — as a standalone application. Core keeps the host shell and
|
|
every platform policy, the module graph stays flat, and Dashboard grouping stays presentation
|
|
configuration.
|
|
|
|
What that pass implemented is the **static contract only**: `manifestVersion: 4` adds one optional
|
|
`entrypoints.ui` field, validated during discovery exactly like the server and schema entrypoints —
|
|
package-relative, inside the package, compiled ESM. Discovery remains inert; nothing imports, mounts,
|
|
or renders that entrypoint.
|
|
|
|
**Phase 6B pass 1 defines the module UI authoring model and host contract.**
|
|
[ADR 0022](decisions/0022-module-ui-authoring-and-host-contract.md) selects React and TypeScript as
|
|
the supported way to author module UI, and defines what a compiled `entrypoints.ui` artifact exports
|
|
and what a host provides it. React is the authoring model but deliberately not the contract: an
|
|
artifact default-exports `defineModuleUi({ id, version, mount })`, and `mount(container, context)`
|
|
takes a DOM element and returns an unmount function, so a module's framework and a host's stay
|
|
independent.
|
|
|
|
The contract lives in `@ekklesia/module-ui-sdk`, a browser-safe shared package with no runtime
|
|
dependencies, consumed by module authors and hosts alike. Its host context is four members —
|
|
`moduleId`, `api`, `principal`, `permissions`. Module UI reaches its own backend through
|
|
`api.request(path)` with a path relative to the module's own API root, never by constructing
|
|
Ekklesia's `/api/v1/modules/<module-id>` prefix, which is what keeps a standalone host possible.
|
|
Client-side permission hints are presentation only; server-side enforcement remains the sole
|
|
authority. Module UI is trusted code in the host's browser realm — there is no sandbox, matching the
|
|
backend trust model rather than overstating it.
|
|
|
|
Core is untouched by this: discovery still validates the `entrypoints.ui` path and never evaluates
|
|
it, and hosts perform their own dynamic import.
|
|
|
|
**Phase 6B pass 2 makes that contract buildable.**
|
|
[ADR 0023](decisions/0023-module-ui-build-pipeline.md) selects esbuild, compiles a module's
|
|
`src/ui/index.tsx` into the browser ESM artifact its manifest declares, and puts every bundler
|
|
option in one `tooling` package so module authors write no build configuration. React is bundled
|
|
rather than externalized, keeping `mount()` the ABI and a module artifact hostable by any host;
|
|
styling is inline style objects only, and a stylesheet import fails the build rather than emitting an
|
|
asset nothing declares. Building remains an authoring step — Core never builds, and discovery still
|
|
only validates the artifact a module shipped. The Dashboard shell, a UI runtime, a design system, a
|
|
stylesheet loading contract, the standalone host, and every feature module remain future work.
|
|
Restart-based discovery, explicit operator-invoked migrations, and the trusted compiled-module model
|
|
are all unchanged.
|
|
|
|
Target architecture not yet implemented includes production approval-provider
|
|
composition, physical storage-bucket provisioning, jobs/workflow automation, richer public resource
|
|
and action contracts, a Dashboard, a Builder, and reference feature modules; none of these are
|
|
scheduled by this document.
|