ekklesiaandClaude Opus 5
8d651c427d
ADR 0021 established that a module may own UI and added a statically
validated, never-executed `entrypoints.ui` path, but deliberately left
five questions open: what the artifact exports, what a host provides,
how one artifact runs under both Ekklesia and a standalone host, what
the browser-side trust model is, and how module UI avoids being welded
to a Dashboard that does not exist. This answers them.
React and TypeScript are the supported module UI authoring model. The
repository already leaned this way: `packages/typescript-config` ships a
`browser.json` preset and a `react-native.json` preset with
`"jsx": "react-jsx"`, and ADR 0002 names browser and React Native
configurations. One framework is supported; every other stays rejected.
React is deliberately not part of the contract. A module's compiled
artifact default-exports `defineModuleUi({ id, version, mount })`, and
`mount(container, context)` takes a DOM element and returns an unmount
function. `id` and `version` are build-artifact identity markers a host
verifies against the manifest, mirroring `defineModuleRuntime` exactly.
A host needs an element and a context, never a matching rendering
library, so a module's framework, a host's framework, and the platform
boundary between them stay independent.
The contract lives in a new `@ekklesia/module-ui-sdk` rather than in
`@ekklesia/module-sdk`, for a concrete reason: that package re-exports
all of `@ekklesia/contracts`, so routing module UI through it would drag
Zod, Drizzle, and semver into every browser bundle. The new package has
no runtime dependencies, and its one dependency on contracts is
type-only — the emitted `host-context.js` is `export {};`, and a test
pins that so it cannot regress.
The host context is four members: `moduleId`, `api`, `principal`, and
`permissions`. Navigation, theme, module configuration, organization
context, and diagnostics are deliberately absent; each needs a design
that does not exist. Module UI reaches its backend through
`api.request(path)` with a path relative to its own API root and never
constructs `/api/v1/modules/<id>/...`, which is Ekklesia's private
deployment detail — a module that builds that URL is silently unhostable
anywhere else. One fixture artifact is mounted under two hosts with
different origins and URL shapes to prove it.
Client-side permission hints are presentation only, and both the docs
and a test say so plainly: a denied hint does not stop the module from
calling its API, because server-side `requirePermission` is the only
authority. Module UI is trusted code in the host's own browser realm —
no iframe, no sandbox — which matches the backend model rather than
overstating it, since a module's server half already holds the API's
database authority.
The boundary guard is narrowed precisely, not removed: `.tsx`, `react`,
and `react-dom` are un-denied and modules may depend on the new
`module-ui-sdk` role. `.jsx`, `.css`, every other framework,
`react-router-dom`, `react-native`, and `@vitejs/plugin-react` stay
denied, layer rules are untouched, and an unsupported framework aliased
behind an allowed name (`"react": "npm:vue@3"`) is resolved and rejected
by its real target. Fixtures prove each case, including that module UI
source still cannot import Core.
Core, apps/api, and the manifest contract are untouched. Discovery still
validates the `entrypoints.ui` path and never evaluates it; hosts
perform their own dynamic import and validate the result with
`parseModuleUiExport`. No Dashboard shell, UI runtime, navigation,
grouping, standalone host, build or styling pipeline, installer,
hot-loading, or feature module is added.
Co-Authored-By: Claude Opus 5 <[email protected]>
94 lines
5.4 KiB
Markdown
94 lines
5.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
Guidance for Claude Code (and other coding agents) working in this repository. This file is
|
|
intentionally short and durable — it points at authoritative sources instead of restating their
|
|
contents, because restated details drift.
|
|
|
|
## What this repository is
|
|
|
|
Ekklesia is a modular, self-hosted church platform built as a strictly layered pnpm/TypeScript
|
|
monorepo:
|
|
|
|
- **Core** (`core/`) owns platform infrastructure: identity, database connectivity, migration
|
|
execution, module discovery/lifecycle, and other feature-agnostic services. Core never imports a
|
|
feature module, a surface, or an app.
|
|
- **Modules** (`modules/*`, template at `templates/module`) are independently versioned product
|
|
packages. They own their own data and migrations, declare capabilities/permissions through
|
|
`@ekklesia/contracts` and `@ekklesia/module-sdk`, and must never import Core, another module, or a
|
|
surface directly. Per ADR 0021 a module may also own its own UI and declare a compiled
|
|
`entrypoints.ui` artifact, authored in React per ADR 0022 against `@ekklesia/module-ui-sdk`. No
|
|
host mounts that entrypoint yet, and `pnpm boundaries` still rejects every non-React UI framework
|
|
and non-`.tsx` presentation source inside a module package.
|
|
- **Surfaces** (future `surfaces/*`) own the containing application shell, navigation, and every
|
|
presentation concern a module does not. They consume public API/client contracts only, never Core
|
|
or module internals directly.
|
|
|
|
These boundaries are enforced by `pnpm boundaries` (`scripts/check-boundaries.ts`), not just
|
|
documented. Read `docs/architecture/repository-boundaries.md` and
|
|
`docs/architecture/platform-architecture.md` before proposing any change that crosses a layer.
|
|
|
|
## ADRs are authoritative
|
|
|
|
`docs/architecture/decisions/` records durable architectural decisions. **Accepted ADRs are
|
|
immutable except for status and cross-reference corrections** — do not edit their content to fit a
|
|
new change. A changed decision gets a new ADR that supersedes the old one. Read the full ADR index
|
|
(`docs/architecture/decisions/README.md`) and every ADR relevant to the area you are touching
|
|
before designing a change; do not assume this file's summary of any decision is complete or
|
|
current.
|
|
|
|
## Read before you design
|
|
|
|
At minimum, read the current versions of:
|
|
|
|
- `docs/architecture/decisions/README.md` and every ADR relevant to your change
|
|
- `docs/architecture/platform-architecture.md` and `docs/architecture/repository-boundaries.md`
|
|
- `README.md` (current platform status — what is and is not implemented)
|
|
- `docs/development/repository-workflow.md` and `docs/development/testing.md`
|
|
- `CONTRIBUTING.md`
|
|
|
|
These files change as the platform evolves. **Inspect the actual current repository state
|
|
(source, tests, package.json scripts, CI workflow) before relying on anything in this file or in
|
|
your own memory of a prior session** — treat stale assumptions as a bug to catch, not a shortcut.
|
|
|
|
## Working conventions
|
|
|
|
- Work on a clean branch off an up-to-date `main`; never commit or push directly to `main`; never
|
|
change branch-protection settings.
|
|
- Keep PRs focused on one bounded slice. Record major architectural changes in an ADR rather than
|
|
burying them in an implementation.
|
|
- Add or update tests when you change a contract or architectural rule. New behavior needs new
|
|
test coverage, not just a passing existing suite.
|
|
- Errors that reach a user, log, CLI, or `pnpm doctor` output must be sanitized: never expose
|
|
secrets, connection strings, raw SQL, raw driver/exception messages, stack traces, causes, or
|
|
machine-specific paths. Match the sanitization pattern already used by
|
|
`core/src/migrations/runner.ts` and `core/src/diagnostics/doctor.ts` rather than inventing a new
|
|
one.
|
|
- Never run a database migration automatically (on import, on startup, in a test that isn't
|
|
explicitly a migration test, or as a side effect of an unrelated command). Migrations are always
|
|
an explicit, operator-invoked action.
|
|
|
|
## Canonical verification commands
|
|
|
|
Run from the repository root; `package.json` is the source of truth if this list and the file
|
|
ever disagree:
|
|
|
|
- `pnpm verify` — the full code-only gate (format, lint, boundaries, typecheck, tests, module and
|
|
migration validation, identity schema drift check, build). Docker-free; never touches a live
|
|
database.
|
|
- `pnpm test:migrations:integration` — live, disposable-PostgreSQL evidence: migration discovery,
|
|
planning, and execution, plus the `apps/api` HTTP transport (signup, sign-in, principal
|
|
resolution, sign-out). Requires Docker. Run this for any change touching either area.
|
|
- `pnpm doctor` — read-only local readiness report. Never treat it as a substitute for `pnpm
|
|
verify` or the integration suite.
|
|
- `pnpm migrations:plan` / `pnpm migrations:apply` — read-only planning vs. mutating execution
|
|
against `DATABASE_URL`. Never run `migrations:apply` without the user's explicit intent.
|
|
- `pnpm api:start` — starts the identity HTTP transport against an already-migrated `DATABASE_URL`.
|
|
It never applies migrations itself. Never run it without the user's explicit intent.
|
|
|
|
## When you're unsure
|
|
|
|
If a task would require weakening an existing ADR's guarantee, introducing a second mechanism
|
|
where one already exists (a second migration runner, a second discovery path, a second config
|
|
system), or exposing something the boundary checker currently blocks, stop and surface the
|
|
conflict instead of working around it.
|