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]>
92 lines
5.2 KiB
Markdown
92 lines
5.2 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; no runtime hosts that entrypoint yet, and `pnpm boundaries` still
|
|
rejects UI source files and UI framework dependencies inside a module package.
|
|
- **Surfaces** (future `surfaces/*`) own all UI and presentation. 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.
|