labhelper/AGENTS.md

AGENTS.md - labhelper

Type: Django 5.2 web app (lab inventory)
Python: 3.13 | DB: SQLite (dev) | Env: .venv/

Essential Commands

# Activate venv first
source .venv/bin/activate

# Dev server
python manage.py runserver              # localhost:8000
python manage.py runserver 0.0.0.0:8000 # all interfaces

# Database
python manage.py makemigrations boxes   # after model changes
python manage.py migrate
python manage.py showmigrations

# Testing
python manage.py test                    # all
python manage.py test boxes              # app only
python manage.py test boxes.tests.BoxModelTests.test_method  # specific

# Custom commands
python manage.py create_default_users    # admin/admin123, staff/staff123, viewer/viewer123
python manage.py clean_orphaned_files --dry-run
python manage.py clean_orphaned_images --dry-run
python manage.py collectstatic           # after CSS changes

Critical Rules

1. NEVER commit/push without explicit permission - wait for user to say "commit and push"
2. Use get_object_or_404() not bare .get() for model lookups
3. Run makemigrations then migrate after any model change
4. Default users: admin/admin123 (superuser), staff/staff123, viewer/viewer123

Data Model

• BoxType → Box (1:N, PROTECT)
• Box → Thing (1:N, PROTECT) — Box.pk is CharField(max=10)
• Facet → Tag (1:N, CASCADE) — Facet.cardinality: single/multiple
• Thing ↔ Tag (M2M)
• Thing → ThingFile, ThingLink (1:N, CASCADE)

Deployment (when instructed)

Full deploy: bump both versions in argocd/deployment.yaml (+0.001), then:

cp data/db.sqlite3 data-loader/preload.sqlite3

Partial deploy: bump main container only, skip DB copy.

Key Directories

• boxes/ — main app (models, views, forms, templates)
• labhelper/ — project settings, base template
• argocd/ — Kubernetes manifests for production
• data-loader/ — init container with preloaded DB

Gotchas

• Template base: labhelper/templates/base.html
• App templates: boxes/templates/boxes/
• Box ID is CharField (e.g., "A1-001"), not auto-increment
• Views use conditional_login_required - bypasses login for IPs in ALLOWED_CIDR_NETS env var
• Markdown via {{ text|render_markdown }} (sanitized with bleach)
• Third-party: django-mptt, sorl-thumbnail, bleach, markdown