62c5454f00
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.
100 lines
5.5 KiB
Markdown
100 lines
5.5 KiB
Markdown
# 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.
|