Add AGENTS.md for AI agent context

2026-05-25 20:18:57 -04:00
parent e7cdac7c44
commit 605353c533
1 changed files with 65 additions and 0 deletions
@@ -0,0 +1,65 @@
+# Canteen Admin Server — Agent Guide
+
+Admin-only FastAPI backend sharing the Canteen Asset Tracker SQLite DB. CRUD for users, customers, locations, rooms, geofences, settings, plus Cantaloupe sync pipeline.
+
+## Stack
+
+- **Python** 3.11+, **FastAPI**, **uvicorn**
+- **openpyxl** — Excel export generation
+- **httpx** — Cantaloupe sync HTTP calls
+- **pytest** — test suite
+
+## Project Structure
+
+```
+admin_server.py           # ~1.7K lines — ALL admin routes in one file
+cantaloupe_sync.py        # APIRouter at /api/admin/cantaloupe — staged import pipeline
+run.sh                    # Launches uvicorn admin_server:app --reload on port 8090
+requirements.txt
+scripts/
+  cantaloupe-sync.sh      # Cron script: export Cantaloupe → POST to sync API
+static/
+  index.html              # Admin SPA frontend
+test_admin_crud.py        # Admin CRUD tests
+test_cantaloupe_sync.py   # Sync pipeline tests
+test_sync_api.py          # Sync API endpoint tests
+```
+
+## How to Run
+
+```bash
+# Dev (with --reload)
+./run.sh
+
+# Prod
+uvicorn admin_server:app --host 0.0.0.0 --port 8090
+```
+
+## Key Architecture
+
+- Shares `assets.db` with `canteen-asset-tracker` via `CANTEEN_DB_PATH` env var (defaults to `../canteen-asset-tracker/assets.db`)
+- Auth: Bearer tokens, admin role required for all routes
+- All routes under `/api/admin/`
+- Sync pipeline: upload Excel → parse → diff → approve/reject
+
+## Production
+
+- **URL:** https://admin.canteen.ourpad.casa
+- **Port:** 8090 (NPMPlus reverse proxy)
+- **No systemd service** — runs via shell script
+- **DB:** Shares SQLite with canteen-asset-tracker (WAL mode, foreign keys)
+
+## Environment Variables
+
+| Var | Default | Description |
+|-----|---------|-------------|
+| CANTEEN_DB_PATH | `../canteen-asset-tracker/assets.db` | Path to shared SQLite DB |
+| CANTALOUPE_EMAIL | — | Cantaloupe login email |
+| CANTALOUPE_PASSWORD | — | Cantaloupe login password |
+| EXPORTS_DIR | `~/cantaloupe-exports` | Excel download directory |
+
+## Pitfalls
+
+- **Single-file backend** — admin_server.py is ~1.7K lines. Routes grouped by entity but not split into modules.
+- **DB locking** — Shares `assets.db` with canteen-asset-tracker. Both use WAL mode so concurrent reads work, but schema migrations need coordination.
+- **Sync pipeline** — `cantaloupe_sync.py` is mounted as APIRouter on the same uvicorn instance; both run in one process.