66 lines
2.3 KiB
Markdown
66 lines
2.3 KiB
Markdown
# 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.
|