shopdb-flask/docs/adr/ADR-015-site-specific-configuration.md

<!-- docmeta
purpose: explanation
audience: developer, adopter
status: current
summary: Where a site own hostnames, paths and defaults are allowed to live, and where they are not.
loadwith: none
-->

# ADR-015: Where a site's own data is allowed to live

- Status: ACCEPTED
- Date: 2026-08-11
- Deciders: ShopDB maintainers
- Relates to: ADR-004 (per-site instances, not multi-tenant), ADR-013 (plugin catalog + lean per-site builds), ADR-014 (schema-lean per-site builds)

## Context

ShopDB is built as a product several GE Aerospace sites can adopt (ADR-004:
each site runs its own instance). It is also developed at one site, against
that site's live fleet. Every feature therefore arrives
carrying that site's hostnames, networks, share paths and vocabulary, and the
fastest way to ship any of them is to write the value where the code needs it.

That is not a hypothetical drift. A scan of `plugins/` and `shopdb/` for a site
host, a site FQDN or a site network returns 19 hits, of which roughly 8 are a
shipped default or a hardcode rather than a comment:

- `plugins/geenforce/seed_display_scope.py` baked one site's own ShopDB URL and
  `device.geaerospace.net` into an inline PowerShell payload. A sister site
  could not override either without editing the source. FIXED 2026-08-14: the
  kiosk base URL now comes from the `site_base_url` setting at seed time and
  from HKLM at run time, and the dispatcher refuses rather than guessing when
  neither is set.
- `plugins/backups/services/registry.py` defaults the backup share root to one site's own
  UNC path.
- `shopdb/core/api/settings.py` ships `device.geaerospace.net` and
  `Printer-{ip}.printer.geaerospace.net` as SETTING DEFAULTS, so another site
  inherits that site's domain silently until someone notices.
- `shopdb/core/models/dashboarddefault.py` holds the same domain a second time
  as a module constant, and `plugins/computers/api/routes.py` a third time as a
  literal fallback.

The problem is not that site-specific values exist - they must. It is that the
repository already has three good mechanisms for them and no rule about which to
use, so each new value lands wherever was convenient. The result reads as drift
because it is unmanaged, not because any single choice was wrong.

Nothing here is a security matter: these are internal hostnames on an air-gapped
network, and `tests/test_docs_publishable.py` already gates what reaches the
public wiki. This is about whether a sister site can adopt the product without
reading our source.

## Decision

A site's own data lives in one of three places, in this order of preference.

**1. A setting, with a NEUTRAL default.** Anything an operator could plausibly
change: hostnames, domains, share paths, networks, base URLs, label prefixes.
The default that ships must be blank or generic, never one site's value. Blank
must be a working state - code reads the setting and degrades sensibly, the way
`display_fqdn_domain` already treats blank as "use the hostname as-is". A
site-specific default is the failure mode this ADR exists to stop: it is
invisible, it looks deliberate, and it is wrong everywhere except here.

**2. A site-namespaced directory.** Anything that is genuinely one site's and
will never be another's, such as the reference site's import loader at
`scripts/site_imports/wjf/`. Never reached by another site's build.

**3. Seed data, not code.** Vocabularies and catalogs, loaded by `flask seed`
and editable per site afterwards.

Fleet-wide convention is NOT site-specific. The `gea-shopfloor-*` imaging types
are a GE fleet taxonomy, not one site's data, and they already carry a per-site
override through the `pctypemap_*` settings. They are out of scope here.

Comments and documentation may name a site where it explains WHY - "part markers
share a machine number at the reference site" is a fact a maintainer needs. Prefer
phrasing the rule generally and the example specifically.

## Enforcement

`scripts/check-naming-and-style.sh`, which already runs in CI, greps `plugins/`
and `shopdb/` for a site host, a site FQDN or a site network, excluding tests
and `site_imports/`.

It shipped in REPORT-ONLY mode, because turning a 19-item backlog into a hard
gate on the day it lands blocks every unrelated commit until someone works
through it. See the amendment below: it now fails the build.

## Consequences

Positive:

- A sister site can adopt without reading our source for values it must change.
- The backlog is visible and counted rather than felt.
- New site-specifics are caught at commit time, in the same place the naming
  rules are already enforced, so there is nothing new to remember.

Negative:

- Report-only means the rule is advisory until someone flips it, and an
  advisory rule can be ignored.
- A neutral default is more code than a working one: every read needs a blank
  case, which is a real cost paid at every call site.
- The pattern list is a denylist and will miss a site value it has not been
  taught. It catches drift, not everything.

## Backlog

CLEARED - see the amendment below. Kept as the record of what the decision was
answering:

- `plugins/geenforce/seed_display_scope.py` - kiosk base URL, FQDN domain, and
  the legacy-shortcut sweep pattern
- `plugins/backups/services/registry.py` - `DEFAULTSHAREROOT`
- `shopdb/core/api/settings.py` - `display_fqdn_domain` and the printer
  hostname pattern defaults
- `shopdb/core/models/dashboarddefault.py` - `DEFAULT_DISPLAY_FQDN_DOMAIN`
- `plugins/computers/api/routes.py` - literal fallback duplicating that default

The domain appears three times in three files, which is its own defect: one
setting, one default, one read.

Cosmetic mentions in comments and UI placeholder text are acceptable under this
ADR and are not part of the backlog, with one exception worth fixing when
convenient: the GE-Enforce settings page shows one site's real CIDRs as its
placeholder, which every site sees.

## Amendment, 2026-08-14

The backlog above is cleared and the scanner now ENFORCES: it fails the build,
and `SITE_LITERALS_ENFORCE=0` is the escape hatch rather than the default. The
report-only period ended for the reason the Consequences section predicted - the
hit count did not move for weeks, because a rule that only prints is read as no
rule.

Three things changed beyond clearing the list:

- The scan covers PowerShell, the installer, the seeds, generated JSON and the
  frontend, case-insensitively, across `plugins/`, `shopdb/`, `scripts/`,
  `deploy/`, `frontend/src/` and `tools/`. Its original scope - three file types
  under two directories - missed every literal that actually reached a second
  site, because those were all in the client scripts and the installer.
- A line may declare itself deliberate with a trailing `ADR-015-OK: <reason>`
  marker. That is for an organisation-wide default which is right at every site
  and configurable anyway, such as the corporate device domain. It is not a
  way to defer work: the marker puts the claim in the diff where a reviewer
  sees it.
- Both publication gates - the export scrub and the docs publishability test -
  carry the site patterns, which neither did. The ADR said this was not a
  security matter because the values were internal to an air-gapped network;
  that was true of the fleet and false of the public mirror, which had been
  carrying a production hostname and a share path.

This amendment is appended rather than edited into the text above, because what
the decision looked like when it was taken is the part worth keeping.