feat: add Dashboard navigation as presentation configuration
CI / verify (pull_request) Successful in 34s
CI / infrastructure-smoke (pull_request) Successful in 12s
CI / migration-smoke (pull_request) Successful in 44s

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]>
This commit is contained in:
ekklesia
2026-08-22 12:44:40 -05:00
co-authored by Claude Opus 5
parent ac5b2b7f6c
commit bd34c9c714
49 changed files with 4866 additions and 213 deletions
+36 -4
View File
@@ -355,10 +355,42 @@ still refused `403` when the UI calls the API anyway. The host owns the containe
and every failure; a broken module costs its own panel, not the shell. See
[ADR 0026](docs/architecture/decisions/0026-minimal-ekklesia-module-ui-host.md).
**This is not the Dashboard.** There is no navigation model, grouping, folders, icons, ordering, home
screen, design system, or client-side routing — the selector is a list of module ids. Sign-in UI, a
production CSP and deployment for the built shell, asset publication beyond the UI entrypoint, React
runtime sharing, the standalone host, and every real feature module also do not exist.
Phase 6D pass 1 gives that shell a real **navigation model** — and pins down the rule it could
easily have broken. A church sees `Media → Livestream, Video` and `Planning → Calendar`, while the
modules underneath stay exactly what they were: flat, independently versioned products with no
parent, no owner, and no folder-derived dependency.
**Grouping is presentation configuration, not module structure.** A group is a label on a rendering
bucket: no manifest, no version, no artifact, no API, no lifecycle, and nothing depends on it.
Placing Livestream and Video in one folder creates no relationship between them, and moving a module
changes one row. *Livestream depends on Video because it calls Video's functionality* is a real
dependency that orders startup; *Livestream is shown under Media* orders nothing. That distinction 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 come out byte-identical every time.
**No manifest change, and no version 5.** `manifest.name` has been required since version 1 and is
already the module's product identity, so the shell simply renders "Livestream" instead of
`livestream`. `suggestedGroup` was 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
would risk a module's suggestion overwriting an administrator's decision.
Two Core tables (migration `0003`) hold groups and placements — server-side, because a church
configures its Dashboard, not one browser; platform-global, because Ekklesia has no organization
model yet. `GET /api/v1/dashboard/navigation` returns the resolved view, layered **on top of** the
host-neutral module UI inventory rather than merged into it, embedding each generic descriptor
untouched. Reading needs the same permission the inventory does; organizing needs a new platform
permission, `core.dashboard.navigation.manage`. A newly installed module appears immediately as
ungrouped with no initialization write; an uninstalled module's placement is retained so reinstalling
restores its position; deleting a group ungroups its modules through the database rather than
application cleanup. See
[ADR 0027](docs/architecture/decisions/0027-dashboard-navigation-and-flat-modules.md).
**Still not the finished Dashboard.** There is no navigation editor or drag and drop, no nested
folders, no icons or colors, no Dashboard Home or widgets, no design system, and no client-side
routing. Sign-in UI, a production CSP and deployment for the built shell, asset publication beyond
the UI entrypoint, React runtime sharing, the standalone host, and every real feature module also do
not exist.
**Security model.** Installed modules are trusted compiled backend code that runs arbitrary
JavaScript in the API process and shares its PostgreSQL role — table prefixes, manifests, permission