Zayin/Ekklesia
3
0
Fork 0
Code Issues 1 Pull Requests 3 Actions Packages Projects Releases 8 Wiki Activity
Files
82cbeef4378efec86de644ee578bcb0426d0478d
Ekklesia/CLAUDE.md
T
ekklesiaandClaude Opus 5 8d651c427d
CI / verify (pull_request) Successful in 30s
Details
CI / infrastructure-smoke (pull_request) Successful in 23s
Details
CI / migration-smoke (pull_request) Successful in 45s
Details
feat: define the module UI authoring model and host contract 
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]>
2026-08-21 20:52:47 -05:00

5.4 KiB
Raw Blame History

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.

Reference in New Issue View Git Blame Copy Permalink