ge-aerospace/shopdb-flask
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: a front door, and one page on how the pieces relate

Browse Source 
The wiki had no entry point worth the name. Its Home page was hardcoded inside
the generator, had drifted into recommending INSTALL-WINDOWS-IIS - the manual
procedure these same docs tell you not to follow for a new site, because it
produces a server the installer then refuses to upgrade - and the page carrying
that warning, llms.txt, was never published at all, because the generator copied
only .md files. The adoption guide had zero inbound links.

START-HERE routes by what a reader came to do: stand up a site, deploy the
shop-floor tools, write a plugin, integrate with the API, understand a decision,
or fix something. It is the shortest correct path per role, not an index - the
sidebar is already the index.

FLEET-ARCHITECTURE is the page nothing else could assume. The server, GE-Enforce,
the asset reporter, the backup collectors and EventSaver were each documented
alone, each assuming a reader who already knew the other four. It draws the
shape, states the rule that explains most of the behaviour - nothing on the
server reaches out to a PC, the fleet asks - and ends with the table that says
which of the five programs to open for a given symptom, since knowing that is
most of the diagnosis.

wikigen renders START-HERE as the landing page rather than a list maintained in
a second place, and publishes llms.txt as LLM-GUIDE.
This commit is contained in:
cproudlock
2026-08-14 16:12:04 -04:00
parent ad335cfc9e
commit 62c5454f00
3 changed files with 168 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
docs/FLEET-ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,99 @@
# How the pieces fit together
ShopDB is a server. Around it are four things that run on shop-floor PCs, each
documented in its own page, and each of those pages assumes you already know how
it relates to the others. This page is that relationship.
## The shape
```
+-------------------------------+
| ShopDB (one per site) |
| Flask API + Vue UI + MySQL |
+-------------------------------+
^ ^ ^ |
reports | | | | serves
(X-API-Key) | | | v
+----------------+ | | | +------------------+
| asset reporter |---+ | | | kiosks, displays |
| on every PC | | | | (browser, HTTPS) |
+----------------+ | | +------------------+
| |
+----------------+ | | +------------------+
| backup |----------+ +----| EventSaver |
| collectors | config revisions | screensaver |
+----------------+ +------------------+
pulls the slide feed
+---------------------------+
| GE-Enforce client | pulls its manifest, applies it,
| scheduled task, SYSTEM | reports the cycle back
+---------------------------+
^ |
| v
manifest the PC's
(share or actual state
HTTPS)
```
Every arrow is one direction on purpose. **Nothing on the server reaches out to
a PC.** The server holds state and answers questions; the fleet asks. That is
what lets a bay behind a firewall, asleep, or on a different network segment be
merely out of date rather than broken - and it is why every one of these tools
degrades to "stale" instead of "failed".
## What each piece is for
| Piece | Direction | What it does | Page |
|---|---|---|---|
| **Asset reporter** | PC to server | Says what this PC is: hostname, serial, type, user, IPs, machine number. Creates the PC record the rest of the system hangs off. | [ADOPTING-AT-ANOTHER-SITE](ADOPTING-AT-ANOTHER-SITE.md) |
| **GE-Enforce client** | both | Pulls the manifest for this PC's type, makes the PC match it, reports what it installed, skipped or failed. | [GE-ENFORCE](GE-ENFORCE.md) |
| **Backup collectors** | PC to server | Post machine configuration (NTLARS/DNC, CMM, part marker, UDC) as revisions, so a controller can be restored and a change can be seen. | [BACKUP-RESTORE](BACKUP-RESTORE.md) |
| **EventSaver** | PC to server | Pulls the slide playlist and shows it when a bay is idle. | [EVENTSAVER](EVENTSAVER.md) |
| **Kiosks and displays** | PC to server | A browser in kiosk mode on a ShopDB route. No client software beyond the browser. | [GE-ENFORCE-DISPLAY](GE-ENFORCE-DISPLAY.md) |
## The three ways a PC talks to the server
**The collector API**, `POST /api/collector/*`, with `X-API-Key`. Used by the
asset reporter and the backup collectors. The key is a managed token scoped to
`collector.ingest` and nothing else, so one recovered off a bay cannot read the
asset register. Idempotent by design: the same report twice changes nothing.
See [COLLECTOR-INTEGRATION](COLLECTOR-INTEGRATION.md) and ADR-006.
**The GE-Enforce API**, `/api/geenforce/*`, with a token scoped to the fetch
scope. Manifests out, cycle reports back. Most PC types still take their
manifest from the SMB share and use this only to report; the display cohort
takes everything over HTTPS, because those PCs have no share.
**Plain public reads.** The slide feed and the kiosk dashboard routes need no
credentials at all, because a screensaver and a wall display have nowhere to
keep one. They are read-only and carry nothing a floor visitor should not see.
## What owns what
The question that decides most arguments: **who is allowed to change this?**
- **ShopDB owns the record.** What a PC is, what it drives, what it should have.
- **The manifest owns the PC's configuration.** If GE-Enforce enforces a value,
editing it on the PC is temporary - the next cycle puts it back. That is the
feature, and it is the single most common surprise.
- **The PC owns its own identity.** Serial, hostname, installed software: the
server records what it is told rather than deciding.
Where two systems both converge state - GE-Enforce and Intune DSC, say - decide
which owns which layer before deploying both, or they will fight in a way that
is very hard to see. [ADOPTING-AT-ANOTHER-SITE](ADOPTING-AT-ANOTHER-SITE.md) has
the recommended split.
## When something looks wrong
| Symptom | The piece to look at first |
|---|---|
| A PC is missing from ShopDB entirely | Asset reporter: never ran, or no collector key |
| A PC is there but its details are old | Asset reporter: stopped running. The dashboard's "PCs not reporting" card is this |
| A PC has the wrong software | GE-Enforce: check its last cycle report, then its manifest scope |
| A bay shows the wrong thing on screen | EventSaver config, or the kiosk dispatcher - both are per PC type |
| A machine has no recent config backup | Backup collector on the controlling PC. "Backups that have stopped" on the dashboard |
| Two PCs claim one machine number | Neither: it is a claim in progress, or a typo. The dashboard card names both |
Each row is a different program on a different schedule. Knowing which one to
open is most of the diagnosis.

64
docs/START-HERE.md Normal file
View File

@@ -0,0 +1,64 @@
# Start here
ShopDB is a per-site asset platform: one instance per plant, plugins for what
each site tracks. These pages document the server, the plugin contract, and the
tools that run on shop-floor PCs.
Find yourself below. Each row is the shortest correct path, not everything that
exists.
## I am standing up ShopDB at a new site
1. [INSTALL-WINDOWS](INSTALL-WINDOWS.md) - one offline installer, start to finish.
2. [OPERATE-WINDOWS](OPERATE-WINDOWS.md) - restart, logs, backups, upgrades.
3. [CSV-IMPORT](CSV-IMPORT.md) if the site's data is in spreadsheets, or
[IMPORT-API](IMPORT-API.md) if there is a source database to script against.
**Do not** follow INSTALL-WINDOWS-IIS or DEPLOY-WINDOWS-IIS for a new site.
Those are the manual procedure, kept for hand-built servers that predate the
installer, and following them produces a server the installer then refuses to
upgrade.
## I am deploying the shop-floor tools
Read [FLEET-ARCHITECTURE](FLEET-ARCHITECTURE.md) first - it is one page and it
is what makes the rest make sense.
Then [ADOPTING-AT-ANOTHER-SITE](ADOPTING-AT-ANOTHER-SITE.md), which has worked
examples for Intune, GE-Enforce and manual installation, and says where each
artifact comes from.
## I am writing a plugin
1. [PLUGIN-QUICKSTART](PLUGIN-QUICKSTART.md) - scaffold and first run.
2. [PLUGIN-HOOKS](PLUGIN-HOOKS.md) - the contract. Authoritative.
3. [PLUGIN-LAB-PRINTEDPARTS](PLUGIN-LAB-PRINTEDPARTS.md) - a real plugin built
end to end, to type along with.
4. [PLUGIN-EXTERNAL-REPO](PLUGIN-EXTERNAL-REPO.md) if it lives in its own
repository, and [CONTRACT-STABILITY](CONTRACT-STABILITY.md) before you choose
a version pin.
## I am integrating with the API
1. [LLM-GUIDE](LLM-GUIDE.md) (`docs/llms.txt` in the repo, also served at
`/api/docs/llms.txt`) - auth, the response envelope, common recipes.
Short, and the envelope section is the part people get wrong.
2. `GET /api/docs` on any running instance - the full spec, browsable.
3. [API-REFERENCE](API-REFERENCE.md) for prose, [COLLECTOR-INTEGRATION](COLLECTOR-INTEGRATION.md)
if you are feeding data in from a PC.
## I am trying to understand why something is built this way
[The ADRs](ADR-001-asset-as-platform-contract.md). They are the decision record,
they say what was rejected and why, and they are the fastest way to avoid
relitigating a settled question. [PROJECT-MAP](PROJECT-MAP.md) lists them all
with their status, along with the current versions and every migration head -
it is generated, so it is never stale.
## Something is broken
- Server: [OPERATE-WINDOWS](OPERATE-WINDOWS.md), then `shopdb-admin.ps1 check -Json`.
- A PC or a bay: the symptom table at the end of
[FLEET-ARCHITECTURE](FLEET-ARCHITECTURE.md) says which piece to open first.
- A deploy that half-worked: [UPGRADE](UPGRADE.md) and
[BACKUP-RESTORE](BACKUP-RESTORE.md).

5
docs/llms.txt
View File

@@ -12,6 +12,11 @@ specialists, and they ask assistants for help. Two documents are authoritative:
- `docs/OPERATE-WINDOWS.md` - restart, logs, backups, upgrades, troubleshooting.
Both ship in `docs/` inside the install directory on every installed server.
`docs/START-HERE.md` routes a reader by what they are here to do;
`docs/FLEET-ARCHITECTURE.md` is one page on how the server, GE-Enforce, the
asset reporter, the backup collectors and EventSaver relate - worth reading
before any of their individual pages, each of which assumes the others.
Another site adopting the shop-floor tools - the asset reporter that feeds the
collector API, and the EventSaver screensaver - should read
`docs/ADOPTING-AT-ANOTHER-SITE.md`. It has worked deployment examples for Intune