shopdb-flask/README.md

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
• Column names: Lowercase, single word, no underscores or dashes
  • Examples: assetid, assetnumber, hostname, isactive, createddate
• Foreign keys: Referenced table name + id
  • Examples: locationid, vendorid, modelnumberid, computertypeid
• Boolean columns: Prefixed with is or has
  • Examples: isactive, isshopfloor, iscolor, isdhcp, islicenced

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
• Query parameters: Lowercase, single word
  • Examples: ?locationid=5, ?isactive=true, ?assettype=computer

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 page
• sort - Sort field
• dir - Sort direction (asc/desc)
• search - Search term
• assettype - 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 twelve 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
• 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.