# 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:

```python
# 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:

```json
{
    "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):

```python
# 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:

```bash
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