ge-aerospace/shopdb-flask
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bf6b353b5227ae6b6dda6c22bca782ecd7dd4940
shopdb-flask/docs/INDEX.md
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

179 lines
12 KiB
Markdown
Raw Blame History

<!-- docmeta
purpose: reference
audience: operator, adopter, developer, integrator
status: current
summary: Every task these docs answer, the smallest page set that answers it, and what that costs to read.
loadwith: none
-->
# Documentation index
Find the row that matches what you are about to do, read the pages in the
"Read" column, and skip everything else. That is the whole intent: these docs
are larger than any one person or agent can hold, so the only useful thing an
index can do is tell you which few pages you actually need.
**Lines** is the total size of that row's page set. It is there so you can see
the cost before you pay it. A one-page row is one page on purpose.
**Derived, not authored.** Every row comes from the `docmeta` block at the top
of the page it names - its `purpose`, `status` and `summary` - and the page
itself is the source of truth. So do not improve a row here: fix the `docmeta`
on the page and bring the row into line with it. `tests/test_docs_index.py`
fails when this file and the pages disagree, when a current page is reachable
from no task row, when a row misstates what it costs to read, and when a link
here or in START-HERE points at a file that is not there.
New to the project and not sure which row is yours: [START-HERE](START-HERE.md)
is shorter and picks for you. An agent should read [llms.txt](llms.txt) first.
## Tasks
### Run a site
Docker is the topology this product line ships, and the only one. There is no
Windows installer here and no IIS procedure to follow.
| Task | Read | Lines |
|---|---|---|
| Stand up a new site on Docker at a connected facility | [DEPLOY](DEPLOY.md) | 500 |
| Stand up a site with no internet at all | [DEPLOY-AIRGAP](DEPLOY-AIRGAP.md) | 180 |
| Build the image where npm cannot reach the registry | [DOCKER-PREBUILT-APPROACH](deployment/DOCKER-PREBUILT-APPROACH.md) | 87 |
| Try the product on a Windows box without building it | [DEV-BUILD-TEST](DEV-BUILD-TEST.md) | 56 |
| Upgrade a Docker or venv site to a newer version | [UPGRADE](UPGRADE.md) | 150 |
| Back up a site, or restore one | [BACKUP-RESTORE](BACKUP-RESTORE.md) | 202 |
| Find a setting, an environment variable or its default | [CONFIG](CONFIG.md) | 356 |
| Decide which plugins this site should carry | [PLUGINS](PLUGINS.md) | 134 |
| Answer whether this site is exposed to a published advisory | [DEPENDENCY-SECURITY](DEPENDENCY-SECURITY.md) | 108 |
| Hand somebody a password without leaving it in a chat | [SECURE-SEND](SECURE-SEND.md) | 157 |
### Fill a site with data
| Task | Read | Lines |
|---|---|---|
| Load starting data from spreadsheets, with no developer | [CSV-IMPORT](CSV-IMPORT.md) | 139 |
| Load starting data from a source database | [IMPORT-API](IMPORT-API.md) + [IMPORT-ADOPTION](IMPORT-ADOPTION.md) | 379 |
| Look up the import wire contract only | [IMPORT-API](IMPORT-API.md) | 283 |
| Load the floor plans, or move every marker onto a redrawn plan | [FLOOR-MAP](FLOOR-MAP.md) | 137 |
| Write a procedure technicians will follow on the floor | [GUIDES](GUIDES.md) | 237 |
| File several devices that share one asset number | [ASSET-COMPOSITION](ASSET-COMPOSITION.md) | 158 |
### Shop-floor PCs
| Task | Read | Lines |
|---|---|---|
| Understand what runs on a bay and which page to open next | [FLEET-ARCHITECTURE](FLEET-ARCHITECTURE.md) | 144 |
| Understand what the collector is before choosing a page | [COLLECTOR-INTEGRATION](COLLECTOR-INTEGRATION.md) | 85 |
| Get the shipped reporters running on a fleet, and prove it | [COLLECTOR-CLIENT-SETUP](COLLECTOR-CLIENT-SETUP.md) + [COLLECTOR-AUTH](COLLECTOR-AUTH.md) | 439 |
| Write a client that posts to the collector API | [COLLECTOR-PAYLOADS](COLLECTOR-PAYLOADS.md) + [COLLECTOR-AUTH](COLLECTOR-AUTH.md) | 691 |
| Decide how a PC authenticates - per-PC credential or shared key | [COLLECTOR-AUTH](COLLECTOR-AUTH.md) | 292 |
| Fix a bay showing the wrong slides | [EVENTSAVER](EVENTSAVER.md) | 144 |
| Install printers from ShopDB, or read the installer endpoints | [PRINTER-INSTALLER](PRINTER-INSTALLER.md) | 140 |
| Point the shop-floor tools at a different site's ShopDB | [ADOPTING-AT-ANOTHER-SITE](ADOPTING-AT-ANOTHER-SITE.md) | 290 |
| Explain why a host's backup is listed as stopped | [BACKUP-STALENESS](BACKUP-STALENESS.md) | 104 |
### Build on the platform
| Task | Read | Lines |
|---|---|---|
| Write and install a first plugin | [PLUGIN-QUICKSTART](PLUGIN-QUICKSTART.md) + [PLUGIN-HOOKS](PLUGIN-HOOKS.md) | 1059 |
| Look up one hook, manifest field or shopdb.api import | [PLUGIN-HOOKS](PLUGIN-HOOKS.md) | 866 |
| Check a plugin against the conventions, and the traps that have bitten people | [PLUGIN-GUIDE](PLUGIN-GUIDE.md) + [PLUGIN-HOOKS](PLUGIN-HOOKS.md) | 1060 |
| Ship a plugin from its own git repository | [PLUGIN-EXTERNAL-REPO](PLUGIN-EXTERNAL-REPO.md) + [PLUGIN-HOOKS](PLUGIN-HOOKS.md) | 1152 |
| Choose how tightly to pin a sister site to the contract | [CONTRACT-STABILITY](CONTRACT-STABILITY.md) | 149 |
| Sign a plugin artifact, or make a site verify signatures | [PLUGIN-SIGNING](PLUGIN-SIGNING.md) | 149 |
| Add a backup kind to the backups plugin | [BACKUP-KINDS](BACKUP-KINDS.md) | 52 |
| Set up a dev environment and contribute a change back | [DEVELOPMENT-SETUP](DEVELOPMENT-SETUP.md) | 390 |
| Call the API: where the generated spec is, which surface owns what, how auth works | [API-REFERENCE](API-REFERENCE.md) | 89 |
| Look up current versions, plugin list or Alembic heads | [PROJECT-MAP](PROJECT-MAP.md) | 94 |
| Find out what has shipped, and what is left before 1.0 | [ROADMAP](ROADMAP.md) | 210 |
| Find which architectural decision governs a question | [adr/README](adr/README.md) | 69 |
| Find the design record behind a shipped feature | [proposals/README](proposals/README.md) | 27 |
**There is no build-along lab on this line.** The five-part tutorial was written
around a plugin this product does not carry, and a tutorial that walks a reader
through a directory they do not have is worse than none. Learn the contract from
PLUGIN-QUICKSTART and PLUGIN-HOOKS, scaffold with `flask plugin scaffold`, and
read `plugins/warranty/` - the smallest bundled plugin that owns tables,
permissions, an asset panel and a dashboard card.
Looking for one endpoint? Do not look in a page. The generated spec is served
at `GET /api/docs` on any running instance and tracked as `docs/openapi.json`;
[llms.txt](llms.txt) is the short version - auth, the response envelope, and
the recipes people get wrong. The API-REFERENCE row above is the pointer to
both, plus the surface and auth orientation a spec cannot give.
### Decisions
One ADR answers one question. Read the one row that matches and stop -
nothing here is a prerequisite for anything else. [adr/README](adr/README.md)
is the authoritative ADR index and the only place that records whether a
decision still holds; the lines below are the pages' own summaries, for
routing.
| Question it settles | Read | Lines |
|---|---|---|
| Why Asset, not the legacy Machine model, is the surface plugin authors may depend on | [ADR-001](adr/ADR-001-asset-as-platform-contract.md) | 200 |
| How the plugin contract is versioned and what core_version a plugin must declare | [ADR-002](adr/ADR-002-plugin-versioning.md) | 68 |
| How a plugin reaches a site: bundled in-tree, or dropped into plugins/ from its own repo | [ADR-003](adr/ADR-003-plugin-distribution.md) | 76 |
| Why every site runs its own instance instead of one multi-tenant deployment | [ADR-004](adr/ADR-004-deployment-topology.md) | 100 |
| How a plugin declares a collector schema so the framework wires the ingest endpoint and auth | [ADR-006](adr/ADR-006-collector-contract.md) | 156 |
| How the product is versioned and released, separately from the plugin contract | [ADR-007](adr/ADR-007-product-versioning-and-releases.md) | 123 |
| Why each plugin owns its own Alembic chain instead of adding tables to the core chain | [ADR-008](adr/ADR-008-plugin-migration-ownership.md) | 131 |
| Why the SPA gates plugin routes, so a disabled plugin URL redirects instead of breaking | [ADR-009](adr/ADR-009-frontend-plugin-gating.md) | 156 |
| The hook contract a plugin uses to contribute UI without hand-editing core Vue files | [ADR-010](adr/ADR-010-frontend-plugin-hooks.md) | 326 |
| Why the equipment domain was renamed to machines and machinetypes became modeltypes | [ADR-011](adr/ADR-011-machines-rename.md) | 75 |
| How a site gets only the plugins it chose, and why curation plus signing is the security model | [ADR-013](adr/ADR-013-plugin-catalog-and-lean-builds.md) | 435 |
| Why a lean site stops creating database tables for plugins it never installed | [ADR-014](adr/ADR-014-schema-lean-per-site.md) | 150 |
| Where a site's own hostnames, paths and defaults are allowed to live, and where they are not | [ADR-015](adr/ADR-015-site-specific-configuration.md) | 156 |
| Why the floor map became buildings and levels instead of one image with stacked floors | [ADR-017](adr/ADR-017-buildings-and-levels.md) | 151 |
| Why metrology instruments are machines, so this product has no measuring-tool asset class | [ADR-018](adr/ADR-018-metrology-instruments-are-machines.md) | 132 |
| Why every endpoint gets its own enrolled secret instead of one fleet-wide shared key | [ADR-019](adr/ADR-019-per-pc-endpoint-credentials.md) | 217 |
## Archive - do not follow these
Nothing below is current guidance and nothing above depends on it. A **legacy**
page is still true but superseded: do not start new work from it. A
**historical** page is a finished migration, a design proposal, or a decision
about something this product line no longer carries, kept only as the record of
why something looks the way it does.
They are listed so you can recognise one if you land on it, and so nobody has
to read one to find out it does not apply. Together they are 1,799 lines that
almost nobody needs.
| Page | Status | What it is | Lines |
|---|---|---|---|
| [IMPORT-LEGACY-ASP](IMPORT-LEGACY-ASP.md) | historical | Record of one classic-ASP shopdb migration: the fan-out routing, the judgement calls and what was left behind. | 163 |
| [ADR-005](adr/ADR-005-equipment-vs-measuringtools.md) | historical | The split of machinery from metrology tools into two plugins. Superseded by ADR-018. | 163 |
| [ADR-012](adr/ADR-012-geenforce-manifest-ownership.md) | historical | Why ShopDB owned GE-Enforce manifests as data. That plugin is not bundled here; ADR-013 and the API-token resource scopes trace back to this decision. | 137 |
| [ADR-016](adr/ADR-016-credential-delivery.md) | historical | The plan for ShopDB-resolved credential targeting. Never built; superseded by ADR-019. | 204 |
| [deployment/PRODUCTION-READINESS](deployment/PRODUCTION-READINESS.md) | historical | The 2026-09-07 assessment of why deployment was hard. Its gap list became the distributed-release item on the roadmap; its recommendation of Windows/IIS was reversed. | 372 |
| [proposals/dashboard-live-fleet](proposals/dashboard-live-fleet.md) | historical | The case for a worst-first dashboard queue. Built; kept as the record of why. | 179 |
| [proposals/device-identity](proposals/device-identity.md) | historical | One durable identity for the device a PC drives. Phase 1 is built; phases 2 and 3 are not started. | 235 |
| [proposals/printer-assignment](proposals/printer-assignment.md) | historical | The design making printers a property of the machine. Shipped, and the shipped behaviour is in PRINTER-INSTALLER. | 346 |
## What the docmeta fields mean
Every page in `docs/` opens with an HTML comment like this one, and this index
is built from those blocks:
```
<!-- docmeta
purpose: howto
audience: operator
status: current
summary: One sentence saying what question this page answers.
loadwith: PAGE-A.md
-->
```
- **purpose** - `tutorial` teaches by doing, `howto` is followed under
pressure, `reference` is looked something up in, `explanation` says why.
- **audience** - `operator`, `adopter`, `developer`, `integrator`.
- **status** - `current`, `legacy` (true but superseded), `historical` (a
record, not guidance).
- **summary** - what this index shows instead of the page.
- **loadwith** - the pages that page is not complete without. Usually `none`.
Where a row above lists two pages, that is where the second one came from.
Reference in New Issue View Git Blame Copy Permalink