Build the plugin set a real site runs, and write down what shipped
The lean-build job proved the delete-a-plugin guarantee with two plugins and four hand-picked marker components. It now builds a real twelve-plugin set, and the assertions follow a rule instead of a hunch: one component from EVERY omitted plugin must be absent, one from EVERY chosen plugin must be present, and the backend tree is checked both ways. An omitted set that grows without its check growing is how a leak ships. CHANGELOG had not been touched across the whole range, so the largest security-behaviour change in the product - per-PC endpoint credentials, the shared-key refusal for enrolled PCs, server pinning, agent 1.20.1 and tray 1.7.1 - had no release record. An [Unreleased] section now carries it, written from the commits rather than from memory. CLAUDE.md and the agent quick-reference stated that ADR-016 bans storing credentials in the registry. It does not, and this fleet depends on HKLM for its collector key and server pins: the next person following that text removes them and silently breaks reporting and pinning on every un-enrolled PC. Corrected, along with two other statements that were false on this branch - the database is MySQL, not PostgreSQL, and column names are lowercase concatenated, not snake_case, which is the opposite of what the gate enforces. The wiki drafts are updated against the code as it stands, each old finding given a verdict with a file and line rather than left as an assertion from a week ago, and a new page records the ADR conformance result - including that the ADR set itself is not on this branch, so nothing here enforces it except the naming and style script. They are also scrubbed of the things that must not reach a published wiki: the site name, the internal git server, developer home paths and the assistant tooling. They now pass the repository's own publishability patterns, which is what the scrub is for.
This commit is contained in:
cproudlock
50
CLAUDE.md
50
CLAUDE.md
@@ -1,12 +1,12 @@
|
||||
# ShopDB Flask - Claude Code Context
|
||||
|
||||
ShopDB is a manufacturing floor asset management system built with Flask, Vue 3, and PostgreSQL, deployed across air-gapped GE Aerospace sites.
|
||||
ShopDB is a manufacturing floor asset management system built with Flask, Vue 3, and MySQL, deployed across air-gapped GE Aerospace sites.
|
||||
|
||||
## Architecture
|
||||
|
||||
- **Backend**: Flask 3.x with SQLAlchemy 2.x, plugin-based architecture
|
||||
- **Frontend**: Vue 3 with Vite, component-based UI with plugin panels
|
||||
- **Database**: PostgreSQL 15+ with Alembic migrations per plugin
|
||||
- **Database**: MySQL 8 with Alembic migrations per plugin (`docker-compose.yml` runs `mysql:8.4`; WJ prod is IIS in front of MySQL 8)
|
||||
- **Deployment**: Docker Compose with gunicorn, air-gapped sites via bundle workflow
|
||||
- **Plugins**: 20+ plugins (computers, endpoints, printers, machines, etc.)
|
||||
|
||||
@@ -27,10 +27,13 @@ Each plugin owns its migration chain in `plugins/{name}/migrations/versions/`.
|
||||
- Migrations run automatically on deploy
|
||||
|
||||
### Database Naming Convention
|
||||
- **Tables**: lowercase concatenated, no underscores (e.g., `printedpart`, `mappeddrives`)
|
||||
- **Columns**: snake_case (e.g., `serial_number`, `last_seen`)
|
||||
- **Indexes/constraints**: follow PostgreSQL conventions
|
||||
- Enforced by `scripts/check-naming-and-style.sh` pre-commit hook
|
||||
- **Tables**: lowercase concatenated, plural, no underscores (e.g., `machines`, `mappeddrives`)
|
||||
- **Columns**: lowercase concatenated, singular, no underscores (e.g., `machineid`,
|
||||
`lastzabbixsync`, `isactive`). NOT snake_case - see CONTRIBUTING.md
|
||||
- **Indexes**: `idx_<table>_<column>`. Underscores are allowed HERE ONLY, because an
|
||||
index is infrastructure and not data
|
||||
- Enforced by `scripts/check-naming-and-style.sh` pre-commit hook, on model attributes
|
||||
AND on the column names a migration creates
|
||||
|
||||
### Branch and Deployment Model
|
||||
- `wj` -> prod (shop floor at WJ site)
|
||||
@@ -54,10 +57,20 @@ Plugins extend ShopDB via:
|
||||
- `frontend/views/` - Vue components auto-discovered by router
|
||||
- `migrations/versions/` - Alembic migrations
|
||||
|
||||
Import from `shopdb.api` for stable surfaces:
|
||||
Import from `shopdb.api` for stable surfaces. Every name has to be in that
|
||||
module's `__all__`; this line used to read
|
||||
`db, Asset, Employee, BasePlugin` and two of the four do not resolve, so the
|
||||
first block a new agent copied raised ImportError:
|
||||
```python
|
||||
from shopdb.api import db, Asset, Employee, BasePlugin
|
||||
from shopdb.api import db, Asset, User, Setting, require_permission
|
||||
# BasePlugin is NOT on that surface. plugin.py takes it from its own module,
|
||||
# which is what every plugins/*/plugin.py in this tree does:
|
||||
from shopdb.plugins.base import BasePlugin, PluginMeta
|
||||
```
|
||||
There is no `Employee` model. The directory is an external read-only database
|
||||
reached through `employee_connection`; the plugin's own row type is
|
||||
`DirectoryEmployee`. See `.claude/QUICK-REFERENCE.md` for the full export list
|
||||
and for the other names that are commonly assumed and are not there.
|
||||
|
||||
## Documentation
|
||||
|
||||
@@ -69,7 +82,7 @@ Full documentation in the GitHub wiki at `../shopdb-flask.wiki/`:
|
||||
- ADR-006: Collector contract (endpoint agent)
|
||||
- ADR-007: Product versioning and releases
|
||||
- ADR-013: Plugin catalog and lean builds
|
||||
- ADR-016: Credential delivery
|
||||
- ADR-016: Credential delivery to the fleet (cmdkey credentials for bays; ACCEPTED, NOT built - it is not about kiosks or device tokens)
|
||||
|
||||
**References**:
|
||||
- `API-REFERENCE.md` - Core API surface
|
||||
@@ -116,7 +129,24 @@ Full documentation in the GitHub wiki at `../shopdb-flask.wiki/`:
|
||||
- **Migration conflicts**: Keep plugin chains linear, coordinate with PLUGIN_TABLE_OWNERS
|
||||
- **Unicode**: ASCII only - check logs, comments, commit messages
|
||||
- **Import surface**: Use `shopdb.api`, not internal paths
|
||||
- **Device tokens**: Kiosks require device_token authentication (ADR-016)
|
||||
- **Kiosk access**: a kiosk route admits a caller on either of two grounds - the
|
||||
per-kiosk device token, or a source address inside that kiosk's CIDR allowlist
|
||||
(`usb_kiosk_allowed_cidrs`, `printedparts_kiosk_allowed_cidrs`) - and both are
|
||||
gated on the kiosk's enable flag. Use `ip_in_cidrs` from `shopdb.api`; do not
|
||||
hand-roll a CIDR parser. `request_ip_allowlisted` is only
|
||||
`ip_in_cidrs(client_ip(request), cidrs)` - the USB kiosk does NOT use it,
|
||||
because it first refuses an address that belongs to the path rather than to a
|
||||
caller (loopback, or a configured trusted proxy). On the shipped Windows stack
|
||||
the X-Forwarded-For rewrite rule is disabled, so every caller arrives as
|
||||
127.0.0.1 and that refusal is what keeps the door shut. The real shape and the
|
||||
full trace are in `.claude/QUICK-REFERENCE.md`. There is no
|
||||
`requires_device_token` decorator
|
||||
- **Fleet credentials are in the registry, deliberately**: the endpoint agent and the
|
||||
GE-Enforce reporters run as SYSTEM with no user to prompt, and read their collector
|
||||
key, base URL and server pins from `HKLM\SOFTWARE\GE\ShopDB`. An enrolled PC's
|
||||
own per-PC credential is DPAPI-protected in a SYSTEM-only directory instead.
|
||||
Nothing forbids the registry hive - ADR-016 names registry provisioning as a
|
||||
recommended first step
|
||||
|
||||
## Work PC Role
|
||||
|
||||
|
||||
Reference in New Issue
Block a user