diff --git a/docs/FLEET-ARCHITECTURE.md b/docs/FLEET-ARCHITECTURE.md new file mode 100644 index 0000000..1f2a5a1 --- /dev/null +++ b/docs/FLEET-ARCHITECTURE.md @@ -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. diff --git a/docs/START-HERE.md b/docs/START-HERE.md new file mode 100644 index 0000000..bd74aae --- /dev/null +++ b/docs/START-HERE.md @@ -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). diff --git a/docs/llms.txt b/docs/llms.txt index ed899ea..d862067 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -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