shopdb-flask/CONTRIBUTING.md

Contributing to ShopDB Flask

Coding Standards

Database Naming Convention

IMPORTANT: No underscores in database identifiers

All database table names and column names must use lowercase concatenated words (no underscores).

Pattern	Good	Bad
Table names	printerdata	printer_data
Column names	passwordhash	password_hash
Foreign keys	machinetypeid	machine_type_id
Index names	idx_printer_zabbix	Allowed for indexes

Intuitive Naming for Non-Technical Users

Database tables and columns should use simple, intuitive names that non-technical users can understand when viewing data or reports.

Avoid	Prefer	Why
printerextensions	printerdata	"data" is clearer than "extensions"
machinerelationships	machinelinks	"links" is simpler (consider)
comtypeid	connectiontypeid	Spell it out when unclear

Guiding principle: If someone unfamiliar with the system looked at a table name, would they understand what's in it?

Examples:

# Good
class PrinterExtension(db.Model):
    __tablename__ = 'printerextensions'

    machineid = db.Column(db.Integer, db.ForeignKey('machines.machineid'))
    lastzabbixsync = db.Column(db.DateTime)
    isnetworkprinter = db.Column(db.Boolean)

# Bad
class PrinterExtension(db.Model):
    __tablename__ = 'printer_extensions'

    machine_id = db.Column(db.Integer, db.ForeignKey('machines.machine_id'))
    last_zabbix_sync = db.Column(db.DateTime)
    is_network_printer = db.Column(db.Boolean)

API Response Keys

API JSON responses should also use lowercase concatenated keys to match database columns:

{
    "machineid": 1,
    "machinenumber": "M001",
    "lastzabbixsync": "2026-01-12T10:00:00Z",
    "isnetworkprinter": true
}

Python Code

Python variable and function names follow standard Python conventions (snake_case for variables/functions, PascalCase for classes):

# Variables and functions use snake_case
machine_type = get_machine_type()
is_valid = validate_input(data)

# Classes use PascalCase
class PrinterExtension:
    pass

File Structure

• Models: shopdb/core/models/ or plugins/<plugin>/models/
• API routes: shopdb/core/api/ or plugins/<plugin>/api/
• Services: shopdb/core/services/ or plugins/<plugin>/services/

Plugin Development

When creating a new plugin:

1. Create directory structure in plugins/<name>/
2. Include manifest.json with metadata
3. Extend BasePlugin class
4. Follow naming conventions above
5. Run flask plugin install <name> to install

Testing

Run tests with:

pytest tests/

Code Review Checklist

• No underscores in table/column names
• API responses use consistent key naming
• Plugin follows BasePlugin interface
• Tests included for new functionality