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
• Applications - Software deployed across the shop floor, with per-PC install tracking
• Endpoints - RMM telemetry reported by the ShopDB agent: metrics, services, inventory, Windows events
• Backups - Per-asset configuration backups with revision history and diffs
• Warranties - Coverage records with vendor warranty lookups
• Knowledge Base and Guides - Reference articles and step-by-step procedures with working checklists
• Notifications - Shopfloor announcements and recognition feed
• Slides - Lobby display and shopfloor screensaver slideshows

Tech Stack

Backend:

• Python 3.14 with Flask
• SQLAlchemy ORM
• MySQL 5.7+ database (5.6 works with extra utf8mb4 config; see the DEPLOY wiki page)
• 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 the DEPLOY wiki page)

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

Source lives here, and a site stands up ShopDB with Docker. Three compose files cover the three situations: docker-compose.yml builds the image from this checkout, docker-compose.pull.yml runs an image published to a registry, and docker-compose.airgap.yml runs an image loaded from a tarball at a site with no internet.

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 the CONFIG wiki page 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 the IMPORT-API page in the project wiki drive the whole migration through documented endpoints (X-Import-Mode preserves original timestamps). scripts/site_imports/ holds the shared import machinery - the resolver, the idempotent journal, the approval packet builder and the WINC machine-adoption writer that the core import routes call.

Which deployment route

Target	Use
Docker, connected	the DEPLOY page in the project wiki (docker-compose.yml or docker-compose.pull.yml)
Docker, air-gapped	the DEPLOY-AIRGAP page in the project wiki (docker-compose.airgap.yml)

For every environment variable and Setting key see the CONFIG page in the project wiki.

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/machines), 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)

Where to start

the START-HERE page in the project wiki routes by what you are here to do - standing up a site, deploying the shop-floor tools, writing a plugin, integrating with the API, or diagnosing something. On the published mirror the same page is the wiki's front door.

Plugin System

ShopDB supports plugins for extending functionality. See CONTRIBUTING.md for plugin development guidelines.

The image bundles these plugins; only the ones a site installs are loaded. The current count and each plugin's version and migration head are in the PROJECT-MAP page in the project wiki, which is generated:

• backups - Per-asset configuration backups (NTLARS/DNC, CMM, part marker, UDC) with revision history and diffs
• computers - Shopfloor PCs and workstations, collector fleet ingest
• endpoints - RMM telemetry from the ShopDB agent: metrics, services, inventory, Windows events
• guides - Step-by-step procedures with images, working checklists and printable output
• knowledgebase - Documentation and troubleshooting articles
• machines - CNC, CMM, and other shop-floor machines
• network - Network devices and subnets
• notifications - Shopfloor notifications and recognition feed
• printers - Extended printer management with Zabbix integration
• slides - Lobby display and shopfloor screensaver slideshows
• tools - Tech Tools: barcode/QR label generation and one-view secure send
• warranty - Warranty records with derived coverage status

Applications is not in that list because it is not a plugin: it is core, has no manifest, and always ships.

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.