e67fe47fe2
Prod grew rows saying both "PC controls 2005" and "2005 controls PC", and a CMM PC showing "<- controls from CMM4" beside its own outgoing link. Only one direction can be true: a PC drives a machine, never the reverse. Nothing stopped it. The duplicate check was keyed on (source, target, type), so the inverse inserted cleanly, and the Add Relationship dialog offers an incoming direction that writes exactly that. The legacy import stores controls the wrong way round as well. Directional creates now refuse the reverse with a 409 naming the row that already holds it, and refuse self-links, which render as a duplicate on the asset's own page and mean nothing. Symmetric types are exempt: Dualpath stores both directions on purpose and the card collapses them. The propagation fan-out got the same guard so a rail meant to spread one direction across sibling bays cannot manufacture a pair. fix-controls-direction only matched source assettype 'machine', so every measuring_tool, printer and network_device row it was written to clean survived it - which is why running it would never have fixed the CMM. It now matches any non-computer controlled BY a computer. New `flask relationships audit` reports what is already stored: reciprocal pairs, self-links, and PCs controlling several assets of one type. Read-only, and it prints each row's label because that usually names the writer outright - collector:* means this code made it, anything else means a person or the import did. That distinction decides the fix for duplicate device assets, which is not in this commit: the collector keys idempotency on its own label, so a device somebody created by hand is invisible to it and it mints another, and the adoption rule needs the audit run against prod before it can be written. Two false positives were found writing it, against the dev database, and both would have made the report useless. A self-link is its own inverse, so it was counted as a reciprocal pair AND printed twice. And Dualpath siblings looked like duplicate devices - a dual-bay machine is one physical machine with one controller and controls is propagated to both bays deliberately. That was 30 of 32 findings, consecutive bay numbers pair by pair.
ShopDB Flask
A modern rewrite of the classic ASP/VBScript ShopDB application using Flask (Python) and Vue 3. This application manages shop floor machines, PCs, printers, applications, and related infrastructure for manufacturing environments.
Overview
ShopDB tracks and manages:
- Machines - CNC equipment, CMMs, inspection systems, etc.
- PCs - Shopfloor computers, engineering workstations
- Printers - Network printers with Zabbix supply integration
- Network devices - Switches, routers, and the subnet browser
- Measuring tools - Gage-lab instruments with calibration tracking
- Applications - Software deployed across the shop floor, with per-PC install tracking
- Employees - Directory, recognition and training notifications
- Warranties - Coverage records with Dell warranty lookups
- USB devices - CMMC check-in/out tracking
- Knowledge Base - Documentation and troubleshooting guides
- GE-Enforce manifests - Imaging/software manifest editing and fleet compliance
Tech Stack
Backend:
- Python 3.14 with Flask
- SQLAlchemy ORM
- MySQL 5.7+ database (5.6 works with extra utf8mb4 config; see docs/DEPLOY.md)
- JWT authentication
- Plugin architecture for extensibility
Frontend:
- Vue 3 with Composition API
- Vue Router for navigation
- Pinia for state management
- Vite build system
Project Structure
shopdb-flask/
+-- shopdb/ # Flask application
| +-- core/
| | +-- api/ # REST API endpoints
| | +-- models/ # SQLAlchemy models
| | +-- schemas/ # Validation schemas
| | `-- services/ # Business logic
| +-- plugins/ # Plugin system
| `-- utils/ # Shared utilities
+-- frontend/ # Vue 3 application
| +-- src/
| | +-- api/ # API client
| | +-- components/ # Reusable components
| | +-- views/ # Page components
| | +-- router/ # Route definitions
| | `-- stores/ # Pinia stores
| `-- public/ # Static assets
+-- plugins/ # Bundled and external plugins
+-- migrations/ # Alembic migration chain (flask db upgrade)
+-- scripts/ # Import and utility scripts
`-- tests/ # Test suite
Naming Conventions
To maintain consistency with the legacy ShopDB database and codebase, the following naming standards apply:
Database
- Table names: Lowercase, single word, no underscores or dashes
- Examples:
assets,computers,printers,businessunits
- Examples:
- Column names: Lowercase, single word, no underscores or dashes
- Examples:
assetid,assetnumber,hostname,isactive,createddate
- Examples:
- Foreign keys: Referenced table name +
id- Examples:
locationid,vendorid,modelnumberid,computertypeid
- Examples:
- Boolean columns: Prefixed with
isorhas- Examples:
isactive,isshopfloor,iscolor,isdhcp,islicenced
- Examples:
Code
- Python variables: Follow database naming where applicable (lowercase, no underscores for model fields)
- JavaScript variables: camelCase for local variables, but match API field names from backend
- Vue components: PascalCase for component names
- CSS classes: Lowercase with dashes for multi-word classes
API
- Endpoints: Lowercase, plural nouns
- Examples:
/api/machines,/api/computers,/api/locations
- Examples:
- Query parameters: Lowercase, single word
- Examples:
?locationid=5,?isactive=true,?assettype=computer
- Examples:
Style Guidelines
- No emojis in code, comments, documentation, or UI
- Keep UI functional and professional
- Dark theme is the default
- Consistent table layouts across all list views
Setup
Prerequisites
- Python 3.14
- Node.js 18+
- MySQL 5.7+ (5.6 works with extra utf8mb4 config; see docs/DEPLOY.md)
ShopDB Flask uses MySQL as the canonical database. SQLite is used only for the
test suite (TestingConfig in shopdb/config.py points at an in-memory
SQLite). Do not run dev or production against SQLite.
Distribution
The application is distributed through the internal GE Aerospace git server. Clone it from there; there is no public package or image registry.
Fast path (Docker)
The Docker image builds the Vue frontend and serves it from the API container, so a container deploy needs no separate Node build step.
cp .env.example .env
# Edit .env: set SECRET_KEY, JWT_SECRET_KEY, DATABASE_URL, CORS_ORIGINS,
# and the MYSQL_* passwords (see docs/CONFIG.md for every variable).
docker compose up -d --build
# Create the schema and seed the platform data (idempotent, safe to re-run):
docker compose exec api flask db upgrade
docker compose exec api flask seed permissions
docker compose exec api flask seed settings
docker compose exec api flask seed reference-data
Then browse to the site and complete the first-run setup wizard at /setup
(it creates the first admin account and captures site identity). To create the
admin headlessly instead of using the wizard:
docker compose exec api flask seed admin --username admin --email admin@facility.example.com
Manual path (venv + Node)
# Backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your database credentials and secrets.
export FLASK_APP=shopdb
flask db upgrade
flask plugin upgrade-all # per-plugin schema (ADR-008)
flask seed permissions
flask seed settings
flask seed reference-data
flask run --port 5001 # MUST be 5001 - the frontend dev server proxies here
# Frontend (separate terminal)
cd frontend
npm install
npm run dev # dev server on :5173
npm run build # production build into frontend/dist (served by Flask)
Complete first-run setup at /setup, or run flask seed admin for a headless
admin account. The repo ships VS Code config in .vscode/ (F5 debugs the
backend; a "Dev site" task runs both servers). A fuller day-one walkthrough,
including VS Code and troubleshooting, is the DEVELOPMENT-SETUP page in the
project wiki.
To import a site's legacy data, use the HTTP import surface: an admin API
token plus docs/IMPORT-API.md drive the whole migration
through documented endpoints (X-Import-Mode preserves original timestamps).
scripts/site_imports/wjf/ is the West Jefferson reference loader.
Which deployment route
| Target | Use |
|---|---|
| Windows Server + IIS (how sister sites run) | docs/INSTALL-WINDOWS.md - one installer .exe, offline, no manual IIS work. Day 2: docs/OPERATE-WINDOWS.md |
| Linux / Docker, air-gapped | docs/DEPLOY-AIRGAP.md |
| Linux / Docker, connected | docs/DEPLOY.md |
For every environment variable and Setting key see docs/CONFIG.md.
Configuration
Environment variables (.env):
| Variable | Description |
|---|---|
DATABASE_URL |
MySQL connection string |
SECRET_KEY |
Flask secret key |
JWT_SECRET_KEY |
JWT signing key |
JWT_ACCESS_TOKEN_EXPIRES |
Access token TTL (seconds) |
LOG_LEVEL |
Logging verbosity |
API Documentation
The REST API follows standard conventions:
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/machines |
List machines (filterable by type) |
| GET | /api/machines/:id |
Get machine details |
| POST | /api/machines |
Create machine |
| PUT | /api/machines/:id |
Update machine |
| DELETE | /api/machines/:id |
Soft delete machine |
Each asset plugin exposes the same CRUD pattern on its own prefix
(/api/computers, /api/printers, /api/network, /api/measuringtools),
and cross-cutting asset endpoints live under /api/assets.
Query parameters for list endpoints:
page- Page number (default: 1)perpage- Items per pagesort- Sort fielddir- Sort direction (asc/desc)search- Search termassettype- Filter by asset type (computer, printer, machine, networkdevice, measuringtool)
Plugin System
ShopDB supports plugins for extending functionality. See CONTRIBUTING.md for plugin development guidelines.
The image bundles thirteen plugins; only the ones a site installs are loaded:
- computers - Shopfloor PCs and workstations, collector fleet ingest
- employees - Employee directory
- geenforce - GE-Enforce imaging/software manifests and fleet compliance
- machines - CNC, CMM, and other shop-floor machines
- measuringtools - Gage-lab instruments with calibration tracking
- knowledgebase - Documentation and troubleshooting guides
- network - Network devices and subnets
- notifications - Shopfloor notifications and recognition feed
- printedparts - 3D-printed part catalogue, kiosk issue tracking and stock alerts
- printers - Extended printer management with Zabbix integration
- slides - TV/kiosk slideshows
- usb - CMMC USB check-in/out tracking
- warranty - Warranty records with Dell lookups
Legacy Migration
This project replicates functionality from the classic ASP/VBScript ShopDB site. Key mappings:
| Legacy | Modern |
|---|---|
| ASP/VBScript | Flask/Python |
| Classic ADO | SQLAlchemy |
| Server-side HTML | Vue 3 SPA |
| Session auth | JWT tokens |
License
Internal use only.