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