ekklesiaandClaude Opus 5
bd34c9c714
Phase 6D pass 1. The shell's navigation was a flat list of module ids, which is not a usable experience — and the obvious fix carries an obvious trap. Letting a module declare its folder, or modelling "Media" as something Livestream and Video belong to, turns a rendering preference into architecture: a folder becomes an owner, membership starts to look like a dependency, and the flat module graph acquires a hierarchy nobody decided on. So the rule comes first: a Dashboard group is a label on a rendering bucket. No manifest, no version, no artifact, no API, no lifecycle; nothing depends on it. Livestream depends on Video because it calls Video's functionality, and that orders startup. Livestream is shown under Media, and that orders nothing. No parent module, child module, owning module, or group-derived dependency appears anywhere in the contracts. No manifest change and no version 5. `manifest.name` has been required since version 1 and already is the module's product identity, so the shell renders "Livestream" instead of `livestream` with nothing added. `suggestedGroup` is deliberately deferred rather than shipped: it would force a hard manifest-version cutover for a hint, and its only correct semantics needs initialization logic that risks a suggestion overwriting an administrator's decision. Defaulting and ownership are different things. Two Core tables (migration 0003) hold groups and placements — server-side, because a church configures its Dashboard rather than one browser; platform-global, because no organization model exists to scope them to. `group_id` is `on delete set null`, so deleting a group ungroups its modules and a dangling reference is impossible. `module_id` carries no foreign key, because modules are packages rather than rows, so a placement for an uninstalled module is retained and restores its position on reinstall. `resolveDashboardNavigation` is a pure function of configuration plus the mountable set: an unplaced module is ungrouped and visible with no initialization write, an absent module renders nothing, empty groups are kept, and ordering is total with the module id as final tie-break. `GET /api/v1/dashboard/navigation` returns the resolved view, layered on top of the host-neutral module UI inventory rather than merged into it — each generic descriptor is embedded untouched, so a standalone host never inherits Dashboard semantics. Reading needs the permission the inventory already needs; organizing needs the new platform permission `core.dashboard.navigation.manage` through a narrow, idempotent, closed-validation mutation contract. No editor UI. The flatness rule is executable: a test discovers real fixtures with a genuine dependency, arranges them four ways including both in one folder and the dependency inverted in presentation, and asserts discovery order, dependency declarations, and the module set stay byte-identical. The end-to-end test organizes a real installation through the real API, mounts a module from inside a group, moves it, and asserts the navigation entry is byte-identical across the move and still mounts the same artifact. The shell's client for the generic inventory became dead code and was removed rather than kept speculatively; the endpoint itself is unchanged. Co-Authored-By: Claude Opus 5 <[email protected]>
64 lines
3.3 KiB
Markdown
64 lines
3.3 KiB
Markdown
# Contributing
|
|
|
|
Ekklesia is being built in verified, reviewable phases. Changes should preserve the dependency
|
|
boundaries described in [repository-boundaries.md](docs/architecture/repository-boundaries.md).
|
|
|
|
Before opening a change, run:
|
|
|
|
```bash
|
|
pnpm verify
|
|
```
|
|
|
|
Migration-runner changes also require the disposable live PostgreSQL suite:
|
|
|
|
```bash
|
|
pnpm test:migrations:integration
|
|
```
|
|
|
|
See the [testing guide](docs/development/testing.md) for the distinction between unit and live
|
|
evidence and for credential-safe troubleshooting.
|
|
|
|
When adding or changing a module manifest, also run `pnpm modules:validate` directly for focused,
|
|
path-aware discovery errors. It is included in `pnpm verify`.
|
|
|
|
If Docker is available, also validate the development infrastructure:
|
|
|
|
```bash
|
|
pnpm infrastructure:config
|
|
```
|
|
|
|
## Package rules
|
|
|
|
- Use strict TypeScript for production packages.
|
|
- Expose supported entry points through package `exports`; do not import another package's
|
|
private source paths.
|
|
- Use `workspace:` ranges for internal package dependencies.
|
|
- Modules own their own UI and author it in React and TypeScript (ADR 0022). A module package may
|
|
contain `.tsx` and depend on `react`, `react-dom`, and `@ekklesia/module-ui-sdk`. Every other UI
|
|
framework, `.jsx`, stylesheets, and other presentation formats remain rejected by
|
|
`pnpm boundaries`. UI source lives at `src/ui/index.tsx` and `pnpm build` compiles it to the
|
|
artifact the manifest declares, via `@ekklesia/module-ui-build` (ADR 0023) — module authors write
|
|
no bundler configuration. Styling is React inline style objects only for now, and no host mounts a
|
|
UI entrypoint yet.
|
|
- Module UI reaches its host only through `@ekklesia/module-ui-sdk` — never
|
|
`@ekklesia/module-ui-host`, which is the host-side loader — and asks the host for its own
|
|
API by relative path — never by constructing `/api/v1/modules/<id>/...`, which is Ekklesia's
|
|
private deployment detail and would break standalone hosting.
|
|
- The containing application shell, navigation, global theme, and platform policy belong to Core and
|
|
the host application, never to a module. Ekklesia's own shell is `surfaces/shell`; it discovers
|
|
installed module UIs through `GET /api/v1/module-ui` and mounts them with
|
|
`@ekklesia/module-ui-host`, and it statically imports no module (ADR 0026).
|
|
- Dashboard groups are presentation configuration, never module structure. Do not add a parent
|
|
module, child module, owning module, or group-derived dependency: real module relationships are
|
|
the dependency contract's job alone, and grouping must never influence discovery, dependency
|
|
ordering, startup, or authorization (ADR 0027). A module declares its display name
|
|
(`manifest.name`); the Dashboard owns where it appears.
|
|
- A surface is browser code. It may depend on browser-safe shared roles only — never
|
|
`@ekklesia/contracts` or `@ekklesia/module-sdk`, whose type graphs pull Node's globals into the
|
|
browser — and it reaches the server over HTTP.
|
|
- Add or update tests when changing a contract or architectural rule.
|
|
- Record major architectural changes in an ADR rather than burying them in an implementation.
|
|
|
|
Runtime registries and aggregate schemas will be produced by later phases. Do not add a manually
|
|
maintained feature-module registry; discovery starts from validated `ekklesia.module.json` files.
|