diff --git a/docs/architecture/decisions/0046-installation-owned-branding.md b/docs/architecture/decisions/0046-installation-owned-branding.md new file mode 100644 index 0000000..f808a35 --- /dev/null +++ b/docs/architecture/decisions/0046-installation-owned-branding.md @@ -0,0 +1,110 @@ +# 0046: Ekklesia's branding is never forced on an installation + +- Status: Proposed +- Date: 2026-10-03 +- Related: [ADR 0021](0021-modules-as-hostable-products.md), + [ADR 0034](0034-host-owned-browser-authentication.md), + [ADR 0037](0037-host-provided-outbound-email.md), + [ADR 0038](0038-email-verification-and-password-recovery.md), + [ADR 0039](0039-shared-design-tokens-and-elements.md), + [ADR 0043](0043-display-offline-code-fallback.md), + [ADR 0045](0045-split-dashboard-and-api-origins.md) + +## Context + +Ekklesia is software a church runs for its own people. The people who use an installation (members, +visitors, volunteers running a screen) know the church, not the software behind it, and the church +decides how it presents itself to them. Today the platform names itself in places those people see: +the sign-in screen asks them to "Sign in to Ekklesia", the Dashboard's heading and page title read +"Ekklesia", emails ask them to verify "your Ekklesia email address", and an offline screen in the +sanctuary says it is "waiting for Ekklesia". + +None of those were decided; they accumulated. This records the rule they should have followed, so +every later screen, message, and module is held to it. + +## Decision + +### The principle + +**Ekklesia's branding is never forced on an installation.** Anything a member, visitor, or volunteer +can see is configurable by the installation and removable entirely. That includes, and is not +limited to: + +- page titles, headings, and the name of the application in a browser tab, an installed web app, or + a bookmark; +- sign-in, verification, recovery, and every other authentication screen; +- emails: the sender's display name, the subject, and the body; +- display screens, pairing screens, and offline and failure screens on a display; +- error pages and error messages a person reads; +- application names and icons, and any "powered by" or attribution text. + +"Removable entirely" means an installation can show its own name, or no product name at all, and in +either case no screen or message a person sees names Ekklesia. + +### What is exempt + +Internal identifiers are not branding and stay as they are: package names, module ids, URL paths +(`/api/v1/…`, `/assets/ekklesia-dashboard/…`), HTTP header names, environment variable names, cookie +names, CSS custom property names, element ids and `data-` attributes, storage, cache, and database +names, and log field names. A person can find them only by opening developer tools or reading +configuration, and renaming them would break installations for no one's benefit. + +Tooling an operator runs to administer the installation (the command-line tools, Doctor, server logs, +and startup messages) names the software being operated, as a package name does, and is exempt too. +So are messages written only for developers: thrown errors that reach a console and never a page, and +build-time diagnostics for module authors. + +### How installations configure it + +The platform takes the installation's name from configuration, once, and uses it everywhere a +person-facing string would otherwise have said "Ekklesia". When no name is configured, the wording is +neutral ("Sign in", "Verify your email address", "Waiting for the server") rather than falling back to +"Ekklesia". The default installation therefore names nothing, which is what makes the principle +checkable: a test can render every person-facing screen and message with no name configured and fail +on any occurrence of "Ekklesia". + +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. +An email's sender display name is the existing `EKKLESIA_SMTP_FROM_NAME` (ADR 0037); its subject and +body use the same installation name. + +Visual identity follows the same rule. The platform ships no logo, favicon, or icon today; any it +ships later must be replaceable by the installation and removable entirely, and must not appear by +default. Colours and type are the installation's theme (ADR 0039), not a mark. + +### It applies to modules + +A module's user-visible text follows the same principle. A module that names its host ("Open the +Ekklesia Dashboard") also ties itself to one host, which ADR 0021 already asks modules not to do. +Modules refer to the host generically ("the Dashboard") or not at all. + +## Consequences + +- Every person-facing string that names the platform today becomes either the configured name or + neutral wording. An implementation slice makes that change and adds the test that keeps it true. +- New screens, emails, and modules are reviewed against this rule; "Ekklesia" in a person-facing + string is a defect. +- Internal identifiers, operator tooling, and developer diagnostics keep the name, so nothing + operational is renamed. +- An installation that wants to credit Ekklesia can do so in its own words; the platform never + inserts that credit. + +## Alternatives + +- **Keep "Ekklesia" as the default and let installations override it.** Rejected: an installation + that never thought to configure it would show the software's name to its people, which is forcing + it by default, and "no occurrence of Ekklesia" could not be tested in the default state. +- **Rename internal identifiers too.** Rejected: invisible to the people this protects, and costly + to every installation and module. +- **A configurable "powered by" line, on by default.** Rejected for the same reason as the first + alternative. +- **Per-string customization of every message.** Not needed for this principle: one installation + name and neutral wording remove the product's name everywhere. Richer copy customization, if + wanted, is separate work. + +## Deferred + +- The implementation: the setting, its delivery to pages and emails, the rewording, and the + regression test. +- Installation-supplied logos, icons, and favicons, and a web app manifest. +- Translation and per-string copy customization. diff --git a/docs/architecture/decisions/README.md b/docs/architecture/decisions/README.md index baf92b0..9f1f2e1 100644 --- a/docs/architecture/decisions/README.md +++ b/docs/architecture/decisions/README.md @@ -54,3 +54,4 @@ ADRs capture durable choices that affect more than one package or phase. - [0043: The display caches its shell and declared code, and nothing else](0043-display-offline-code-fallback.md) — Accepted - [0044: Ekklesia ships one self-hosted reference deployment, composed from pinned sources](0044-self-hosted-reference-deployment.md) — Accepted - [0045: The Dashboard and the API may live on separate origins](0045-split-dashboard-and-api-origins.md) — Proposed +- [0046: Ekklesia's branding is never forced on an installation](0046-installation-owned-branding.md) — Proposed