ge-aerospace/shopdb-flask
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3c91e7c3147af465176f56721a1dd02163e662e0
shopdb-flask/CLAUDE.md
cproudlock 69a7997dc4 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.
2026-09-18 13:31:25 -04:00

7.2 KiB
Raw Blame History

ShopDB Flask - Claude Code Context

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: 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.)

Critical Constraints

ADR-015: Site-Specific Configuration

Site literals (building names, printer models, machine types) MUST live in:

  • shopdb/core/settings/ - Site settings (buildings, roles, etc.)
  • shopdb/core/seed/ - Initial data SQL
  • scripts/site_imports/ - Import tools for Maximo/WINC data

NEVER hardcode site-specific data in plugin code or migrations.

ADR-008: Plugin Migration Ownership

Each plugin owns its migration chain in plugins/{name}/migrations/versions/.

  • Migrations run in dependency order defined in PLUGIN_TABLE_OWNERS
  • Each plugin's chain must be linear (no branches)
  • Migrations run automatically on deploy

Database Naming Convention

  • 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)
  • dev -> ops (monitoring/pilot sites)
  • main -> nothing (GitHub public mirror only)
  • Three air gaps: dev PC <-> work PC <-> GitHub
  • Bundles carry code across gaps (pull-shopdb-bundle.cmd, fetch-wilm-branch.cmd)

Code Style

  • Plain ASCII only - no unicode, emojis, or em-dashes
  • No LLM attribution comments (no "Co-Authored-By: Claude")
  • Minimal comments - code should be self-documenting
  • No banned shorthand (e.g., "config" not "cfg", "initialize" not "init")

Plugin Contract

Plugins extend ShopDB via:

  • plugin.py - BasePlugin subclass with manifest, routes, hooks
  • models/ - SQLAlchemy models
  • api/ - Flask blueprints and routes
  • frontend/views/ - Vue components auto-discovered by router
  • migrations/versions/ - Alembic migrations

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:

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

Full documentation in the GitHub wiki at ../shopdb-flask.wiki/:

Critical ADRs:

  • ADR-001: Asset as platform contract
  • ADR-004: Deployment topology (air-gapped sites)
  • ADR-006: Collector contract (endpoint agent)
  • ADR-007: Product versioning and releases
  • ADR-013: Plugin catalog and lean builds
  • 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
  • PLUGIN-DEVELOPMENT.md - Plugin authoring guide
  • DEPLOYMENT.md - Deploy runbooks per site
  • TESTING.md - Test patterns and CI

Development Workflow

  1. Feature branches off dev or wj
  2. Run tests: pytest -v (REQUIRED before claiming completion)
  3. Check naming/style: scripts/check-naming-and-style.sh (REQUIRED before commit)
  4. Bundle for other PC or push to GitHub
  5. PR to wj (for prod) or dev (for ops)

Boundaries & Constraints

DO NOT:

  • Edit generated files (frontend/dist/, docs/openapi.json)
  • Change dependencies (requirements.txt, package.json) without approval
  • Commit code with unicode/emojis (plain ASCII only)
  • Hardcode site-specific data (buildings, models, etc.) - use settings/seed
  • Skip tests or pre-commit hooks
  • Break plugin migration chains (keep linear, coordinate via PLUGIN_TABLE_OWNERS)

ALWAYS:

  • Run pytest -v before claiming work complete
  • Run scripts/check-naming-and-style.sh before committing
  • Use shopdb.api imports, not internal paths
  • Keep database table names lowercase concatenated
  • Reference ADRs by number when making architectural decisions
  • Verify bundle/deploy scripts work before pushing to branches

Testing Patterns

  • Feature tests in tests/test_plugins/test_{plugin}_{feature}.py
  • Use fixtures from conftest.py (app, client, db_session)
  • Test migrations with test_plugin_migrations.py
  • Frontend specs alongside components: *.spec.js

Common Pitfalls

  • Site data in code: Use settings/seed, not hardcoded values
  • 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
  • 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

This machine (work PC):

  • Has GitHub credentials (ge-aero/shopdb-flask)
  • Carries bundles between dev PC and GitHub
  • Deploys to prod and ops servers
  • Mirrors wilm branch from GitHub to gitea

For active development, use the dev PC with gitea.

Reference in New Issue View Git Blame Copy Permalink