canteen-asset-tracker/AGENTS.md

Canteen Asset Tracker — Agent Guide

Mobile-friendly webapp for tracking physical assets with barcode scanning, OCR sticker reading, and GPS check-ins. The main technician-facing application in the Canteen stack.

Stack

• Python 3.11+, FastAPI, uvicorn
• SQLite (WAL mode, foreign keys)
• pytesseract — OCR for ConnectID stickers
• Pillow, piexif — image processing
• Frontend: vanilla HTML/CSS/JS (~200KB SPA), Leaflet maps, ZXing barcode scanner
• Tests: pytest

Project Structure

server.py                 # ~2.5K lines — ALL backend routes, DB, auth, OCR in one file
openapi.yaml              # Shared API contract (source of truth for frontend)
requirements.txt

static/
  index.html              # SPA frontend (~200KB, no build step)
  sw.js                   # Service worker for offline support
  app-release.apk         # Companion Android APK

docs/
  ADMIN_GUIDE.md          # Admin operations guide
  USER_GUIDE.md           # End-user operations
  FEATURES.md             # Feature catalog
  images/                 # Screenshots for docs

scripts/                  # Data migration and helper scripts
PROJECT.md                # v3 project structure doc
TEST_PLAN.md              # Test plan
TEST_PLAN_MAP.md          # Map test plan

How to Run

# Production (generates self-signed TLS cert, auto-installs deps, backs up DB)
./start.sh

# Quick restart
./restart_server.sh

Key Architecture

• Single-file backend — server.py contains routes, DB models, auth, OCR, and geolocation
• OCR: Extracts last 5 digits from XXXXX-XXXXXX Connect ID sticker format via Tesseract
• Auth: Bearer token system, role-based (technician + admin)
• DB: assets.db — SQLite with WAL mode, foreign keys enabled
• Frontend: Pure vanilla JS SPA — no build step, no npm dependencies

Production

• URL: https://canteen.ourpad.casa
• Port: 8901 (HTTPS, self-signed cert → NPMPlus reverse proxy)
• Startup: start.sh generates self-signed cert, backs up DB, starts uvicorn
• No systemd — runs via nohup from start/restart scripts

Environment Variables

Var	Description
CANTEEN_DB_PATH	Path to assets.db (default: ./assets.db)

Related Projects

Project	What it does
canteen-admin-server	Admin CRUD API, shares same SQLite DB
canteen-seed-import	Seed data import from Cantaloupe CSVs
photo-geotagger	Batch GPS updater using same assets.db
exif-test	EXIF/OCR validation against this DB
cantaloupe-downloader	CLI to export machine data from Cantaloupe

Pitfalls

• Single-file backend — server.py is ~2.5K lines; routes, DB, and OCR all in one file
• DB shared across canteen-admin-server, photo-geotagger, seed-import, exif-test — schema changes must be coordinated
• HTTPS — start.sh generates self-signed cert every restart; ports 8901 (production) vs 8904 (dev)
• OCR requires Tesseract installed system-wide (apt install tesseract-ocr)