Files

cproudlock 534f179ee6 Make main the lean product a site receives

main was 16 days and 259 commits behind the line the product is actually built
on, at contract 0.30.0 against 0.35.0, with no per-PC credential code at all. It
was neither current nor curated - just stale. This brings it forward and, at the
same time, makes it mean something: main is what a receiving site installs, and
nothing else.

WHAT IT CARRIES. Twelve plugins - backups, computers, endpoints, guides,
knowledgebase, machines, network, notifications, printers, slides, tools,
warranty - plus applications, which is manifest-less core and always ships. The
only manifest dependency inside that set is endpoints on computers, and both are
in it, so the closure is self-contained.

WHAT IT DOES NOT. employees, geenforce, measuringtools, printedparts and usb
stay on the site line. So do the Windows installer tree, the VM rehearsal
helpers, the agent tooling config, one site's data loader, the internal audit
and findings records, and the planner spreadsheet. 1,135 tracked files against
1,438.

A REMOVAL THAT BREAKS THE APP IS NOT A REMOVAL, and two nearly shipped:

deploy/site-profile-universal.json still named all seventeen plugins. It is the
file docs/DEPLOY.md tells a site to provision from, so a fresh install would
have failed at `flask plugin apply-profile` with PluginError - the first thing a
receiving site does, broken by the branch meant to serve them. It now names the
twelve that exist, and its comment says the two must agree.

agent/ was never refreshed. Whoever populated this branch copied shopdb/,
plugins/, frontend/ and tests/ from the site line and left the agent tree at its
September state: 22 C# and PowerShell sources missing, including AgentCredentials,
EnrollmentService, AgentHttpFactory and the fleet-alert client, plus one file the
site line had deleted still present. The old tree is internally consistent, so it
compiles, and nothing in CI builds it - every gate was green over a server that
speaks enrollment and per-PC credentials to a bundled agent source that cannot.
Resynced whole.

DECISIONS THIS ENCODES, rather than defers:

- The plugin-authoring lab builds printedparts, whose manifest depends on
  employees, so it could not stay. The lab remains on the site line and main
  ships no build-along tutorial. That is a real loss for an adopting developer
  and is recorded here rather than discovered later.
- Recognition, Training and Recertification notifications are no longer seeded.
  Each splits one notification into a card per employee and renders a photo,
  which needs a plugin this branch does not bundle. Seeding them would offer an
  author a type that cannot resolve anybody. A site that installs employees gets
  them from that plugin's own seed.
- Windows/IIS is documented as the legacy path throughout, and the README leads
  with Docker, because that is what a receiving site gets.

The API description is regenerated for THIS branch - 347 paths and 483
operations, down from 415 and 573 - so the published contract describes what is
here rather than what the site line serves. docs/CONFIG.md lost the two
measuring-tool label keys the code no longer declares, which two lanes had
decided opposite ways.

Suite: 3124 passed, 6 skipped. Naming and style gates pass. The docs gates run
rather than skip, and every index line count is derived from the file it names.

2026-09-19 11:24:40 -04:00

7.4 KiB

Raw Blame History

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.

7.4 KiB Raw Blame History