shopdb-flask/CLAUDE.md

ShopDB Flask Project

Modern rewrite of the classic-ASP shopdb. Built as a framework so sister GE Aerospace sites can adopt it. Plugin system is the product.

Database

• Active database: shopdb_flask (MySQL, asset-based schema)
• Legacy database: shopdb (Classic ASP schema, used only for one-time data import via scripts/import_from_mysql.py)
• Connection: .env file. See .env.example.

Architecture decisions live in migrations/adr/. Read those before making schema or contract changes.

• ADR-001: Asset model is the platform contract (Machine retires) - ACCEPTED
• ADR-002: Plugin contract versioning (semver) - ACCEPTED
• ADR-003: Plugin distribution model (in-tree bundled + filesystem-based external) - ACCEPTED
• ADR-004: Deployment topology (per-site instances, not multi-tenant) - ACCEPTED
• ADR-005: Equipment vs measuringtools plugin scope - ACCEPTED
• ADR-006: Plugin collector contract pattern - ACCEPTED

Coding convention

CONTRIBUTING.md defines naming rules (DB tables, columns, Python, JS, Vue, API). Pre-commit hook at scripts/check-naming-and-style.sh enforces them. Read CONTRIBUTING.md before naming any new identifier.

Current state (as of 2026-05-08)

Wired in

• App factory pattern, Flask 3 + SQLAlchemy + Flask-Migrate + JWT + Marshmallow + CORS + Caching
• 6 plugins: computers, equipment, network, notifications, printers, usb
• Plugin contract: BasePlugin ABC, PluginMeta, registry, dependency-aware loader
• JWT auth with refresh tokens, audit logging, system settings, user management
• Frontend: Vue 3 + Pinia + Vite, dynamic plugin routing, dark mode default
• Search across all plugins via get_searchable_fields hook
• Asset relationships (cross-plugin)

In progress / partial

• Dual model coexistence: legacy Machine and new Asset both live. ADR-001 settles direction (Asset wins). Migration plan is the next concrete deliverable.
• Plugin verification: 6 plugins follow BasePlugin interface but no contract test asserts compliance. Skill enforcing-plugin-contract and the contract test suite are pending.
• Tests: hollow. tests/conftest.py exists but uses Flask-SQLAlchemy 2.x patterns that error on 3.x. No actual test files. Skill pinning-flask-behavior covers the rebuild.

Pending

• Alembic versions directory exists (migrations/versions/) but is empty. No migrations have been generated yet. Run flask db init is partial; need flask db migrate to capture current schema.
• Plugin scaffold CLI (flask plugin new <name>)
• Plugin author docs (docs/PLUGIN-QUICKSTART.md, docs/PLUGIN-REFERENCE.md)
• Per-site deploy story (Dockerfile, docs/DEPLOY.md)
• Frontend hook contract (asset-detail, map markers, search results)

Quick start

# Start dev environment
~/start-dev-env.sh

# Activate venv and install deps
cd /home/camp/projects/shopdb-flask
source venv/bin/activate
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with DB credentials, JWT secrets

# Create / update database tables
flask db-utils create-all

# Seed reference data
flask seed reference-data

# Restart services
pm2 restart shopdb-flask-api shopdb-flask-ui

Service URLs

• Flask API: http://localhost:5001
• Flask UI: http://localhost:5173
• Legacy ASP (data source for one-time import): http://192.168.122.151:8080

Plugin structure

plugins/
  <plugin_name>/
    __init__.py
    plugin.py          # BasePlugin implementation
    manifest.json      # Plugin metadata (name, version, dependencies, api_prefix)
    models/
      __init__.py      # Export all models
      <model>.py       # SQLAlchemy models
    api/
      __init__.py
      routes.py        # Flask Blueprint
    services/          # Optional, business logic
    schemas/           # Optional, marshmallow schemas
    migrations/        # Optional, plugin-specific Alembic migrations

Each plugin must have:

• models/__init__.py exports all models
• plugin.py extends BasePlugin
• manifest.json with metadata (single source of truth per ADR-002)
• No direct imports from core code (use the contract surface defined in ADR-001)

Key files

• shopdb/__init__.py - app factory, blueprint registration
• shopdb/plugins/base.py - BasePlugin ABC, PluginMeta dataclass
• shopdb/plugins/loader.py - filesystem discovery, dependency-aware loading
• shopdb/core/api/assets.py - example of optional plugin imports
• frontend/src/router/index.js - frontend routing
• frontend/src/components/AppSidebar.vue - navigation menu
• migrations/adr/ - architecture decision records

Migration notes

• migrations/DATA_MIGRATION_GUIDE.md - one-time import from legacy ASP shopdb
• migrations/MIGRATE_USB_DEVICES_FROM_EQUIPMENT.md - USB device migration from equipment table
• migrations/FIX_LOCATIONONLY_EQUIPMENT_TYPES.md - LocationOnly equipment type fix
• migrations/PRODUCTION_MIGRATION_GUIDE.md - production import methods
• migrations/rename_underscore_columns.sql - one-time rename of snake_case columns to lowercase concatenated (per CONTRIBUTING.md)
• migrations/versions/ - Alembic versions (currently empty)