canteen-admin-server/AGENTS.md

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

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