ADR 0046's startup-configured branding conflicts with DESIGN.md's Settings-managed branding (name, SVG logo, show/hide) #101

New Issue

2026-10-14T13:03:17Z

ekklesia-bot commented

2026-10-14 13:03:17 +00:00

What I observed

ADR 0046 (Ekklesia's branding is never forced on an installation) is still Proposed, and its configuration model does not match what the product design contract now requires for branding.

ADR 0046 (docs/architecture/decisions/0046-installation-owned-branding.md, at 44430b5):

line 3: Status: Proposed
line 59: "The platform takes the installation's name from configuration, once, and uses it everywhere…"
line 66: "Browser pages receive the name the way they receive the API origin (ADR 0045): the API renders it into the page it serves at startup, so the image stays generic and nothing is decided at build time."
"The platform ships no logo, favicon, or icon today; any it ships later must be replaceable…"

DESIGN.md (the current product/interface authority, kept beside the repositories):

§2.1 and §4.2: church branding in the Dashboard shell is optional; a church may show its logo/name or hide either or both; the sidebar shows logo + name when expanded and the logo only when collapsed.
§3.4: Dashboard branding supports church name, SVG logo, optional separate light/dark logo treatment, and an optional app/favicon override. SVG is the preferred logo format (locked decision 28).
§9: Branding / Theme is a Settings category; §3.7 theme editing has live preview and reset-to-defaults.
ROADMAP §5.3 lists Branding as an initial Settings category, and the Stage 1 exit criteria include "User-facing product branding is configurable and not hard-coded."

The conflict

ADR 0046's mechanism is an operator setting read once at startup and rendered into the page bytes (the page's strong ETag is computed from those bytes in apps/api/src/dashboard-host-assets.ts). DESIGN.md expects an administrator to change the name, logo, and show/hide choices from Settings at run time, with logos as uploaded SVG. These need different architecture:

where branding lives (environment variable vs. a Core table edited through the API);
how the Dashboard page and display host receive it (rendered at startup vs. fetched or rendered per request, and what that does to the page's fixed-snapshot ETag model);
how an uploaded SVG is stored (object storage?) and made safe to render (SVG can carry script; there is no SVG trust decision yet; ADR 0027 also deferred icons for this reason);
whether display and email presentation follow the same source.

The principle in ADR 0046 (no forced Ekklesia branding, neutral wording when nothing is configured) matches DESIGN.md. Only the configuration/delivery model is in question.

Impact

Blocks designing the Stage 1 branding slice (sidebar logo/name, Settings → Branding) without first deciding which model holds. Anyone implementing ADR 0046 as written would build a startup-only name that DESIGN.md then requires replacing.

Suggested options

Accept ADR 0046's principle and write a new ADR for runtime, Settings-managed branding (Core table plus API, served to the shell after bootstrap; the startup name remains only as a pre-sign-in fallback, or goes away).
Keep a startup-configured name for pre-authentication screens (sign-in, display pairing) and add Settings-managed branding for the authenticated Dashboard. Two sources, so the precedence must be explicit.
Amend DESIGN.md if runtime-editable branding is not actually intended for 1.0.

What I did not look at

Email branding (EKKLESIA_SMTP_FROM_NAME), the display host's pairing/offline screens, and favicon/app-icon delivery in detail.

Found by Claude while planning Ekklesia Stage 1 (Dashboard / UX / Settings / Platform Management Foundation) and implementing the first slice, Dashboard URL routing.

## What I observed ADR 0046 (*Ekklesia's branding is never forced on an installation*) is still **Proposed**, and its configuration model does not match what the product design contract now requires for branding. **ADR 0046** (`docs/architecture/decisions/0046-installation-owned-branding.md`, at `44430b5`): - line 3: `Status: Proposed` - line 59: "The platform takes the installation's name from configuration, once, and uses it everywhere…" - line 66: "Browser pages receive the name the way they receive the API origin (ADR 0045): the API renders it into the page it serves at startup, so the image stays generic and nothing is decided at build time." - "The platform ships no logo, favicon, or icon today; any it ships later must be replaceable…" **DESIGN.md** (the current product/interface authority, kept beside the repositories): - §2.1 and §4.2: church branding in the Dashboard shell is optional; a church may show its logo/name or hide either or both; the sidebar shows logo + name when expanded and the logo only when collapsed. - §3.4: Dashboard branding supports church name, SVG logo, optional separate light/dark logo treatment, and an optional app/favicon override. SVG is the preferred logo format (locked decision 28). - §9: *Branding / Theme* is a Settings category; §3.7 theme editing has live preview and reset-to-defaults. - ROADMAP §5.3 lists Branding as an initial Settings category, and the Stage 1 exit criteria include "User-facing product branding is configurable and not hard-coded." ## The conflict ADR 0046's mechanism is an operator setting read **once at startup** and rendered into the page bytes (the page's strong `ETag` is computed from those bytes in `apps/api/src/dashboard-host-assets.ts`). DESIGN.md expects an administrator to change the name, logo, and show/hide choices **from Settings at run time**, with logos as uploaded SVG. These need different architecture: - where branding lives (environment variable vs. a Core table edited through the API); - how the Dashboard page and display host receive it (rendered at startup vs. fetched or rendered per request, and what that does to the page's fixed-snapshot `ETag` model); - how an uploaded SVG is stored (object storage?) and made safe to render (SVG can carry script; there is no SVG trust decision yet; ADR 0027 also deferred icons for this reason); - whether display and email presentation follow the same source. The *principle* in ADR 0046 (no forced Ekklesia branding, neutral wording when nothing is configured) matches DESIGN.md. Only the configuration/delivery model is in question. ## Impact Blocks designing the Stage 1 branding slice (sidebar logo/name, Settings → Branding) without first deciding which model holds. Anyone implementing ADR 0046 as written would build a startup-only name that DESIGN.md then requires replacing. ## Suggested options 1. Accept ADR 0046's principle and write a new ADR for runtime, Settings-managed branding (Core table plus API, served to the shell after bootstrap; the startup name remains only as a pre-sign-in fallback, or goes away). 2. Keep a startup-configured name for pre-authentication screens (sign-in, display pairing) and add Settings-managed branding for the authenticated Dashboard. Two sources, so the precedence must be explicit. 3. Amend DESIGN.md if runtime-editable branding is not actually intended for 1.0. ## What I did not look at Email branding (`EKKLESIA_SMTP_FROM_NAME`), the display host's pairing/offline screens, and favicon/app-icon delivery in detail. --- Found by Claude while planning Ekklesia Stage 1 (Dashboard / UX / Settings / Platform Management Foundation) and implementing the first slice, Dashboard URL routing.

ekklesia-bot added the found-by-claude label 2026-10-14 13:03:17 +00:00

ekklesia-bot referenced this issue

2026-10-14 13:11:14 +00:00

feat(shell): give every Dashboard page a real URL, with modules at /<module-id> (Stage 1, ADR 0057) #103

Zayin_Admin referenced this issue from a commit

2026-10-14 22:49:58 +00:00

feat(shell): collapsible sidebar, account menu, and phone drawer

ekklesia-bot referenced this issue

2026-10-14 22:50:27 +00:00

feat(shell): collapsible sidebar, account menu, and phone drawer (Stage 1, ADR 0058) #104

Sign in to join this conversation.