Add AGENTS.md for AI agent context

2026-05-25 20:18:57 -04:00
parent 34da18530f
commit 7c965b4262
1 changed files with 84 additions and 0 deletions
@@ -0,0 +1,84 @@
+# 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
+
+```bash
+# 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`)