canteen-asset-tracker/README.md

Canteen Asset Geolocation Tool

Mobile-friendly webapp for tracking physical assets with barcode scanning and GPS check-ins. Built with FastAPI + SQLite + vanilla JS.

Quick Start

./start.sh

Then open https://<server-ip>:8901 on your phone. Accept the self-signed cert warning.

Default Login

The server seeds a default admin account on first startup:

Field	Value
Username	admin
Password	changeme

Change this password on first login via the Settings → Users tab.

Features

• Scan tab — Barcode scanning via camera. Auto-looks up assets or offers to create new ones.
• Assets tab — Browse, search, filter, create, edit, delete assets. View check-in history per asset.
• Dashboard tab — Stats: total assets, check-ins, breakdown by category and status. CSV export.
• GPS auto-acquired on page load for location-tagged check-ins.

Tech Stack

Layer	Tech
Backend	FastAPI + SQLite (WAL mode)
Frontend	Vanilla HTML/CSS/JS
Scanner	ZXing library (CDN)
TLS	Self-signed cert, port 8901

API

Base URL: https://<host>:8901

Method	Endpoint	Description
GET	/health	Health check
POST	/api/assets	Create asset
GET	/api/assets	List assets (filterable)
GET	/api/assets/search?barcode=	Lookup by barcode
GET	/api/assets/{id}	Get single asset
PUT	/api/assets/{id}	Update asset
DELETE	/api/assets/{id}	Delete asset + check-ins
POST	/api/checkins	Create check-in
GET	/api/checkins	List check-ins (filterable)
GET	/api/stats	Dashboard stats
GET	/api/export/assets	Export assets CSV
GET	/api/export/checkins	Export check-ins CSV
POST	/api/geofences	Create geofence (opt. user_ids)
GET	/api/geofences	List geofences (includes assigned users)
PUT	/api/geofences/{id}	Update geofence (+ reassign users)
DELETE	/api/geofences/{id}	Delete geofence
GET	/api/users/{id}/geofences	List geofences assigned to a user
GET	/api/locations	List locations
GET	/api/locations/{id}	Get location with rooms
GET	/api/rooms	List rooms
GET	/api/activity	Activity feed

Asset fields

barcode (unique, required), name (required), description, category (Furniture/Appliances/Utensils & Serveware/Equipment/Other), status (active/maintenance/retired), photo_path, created_at, updated_at.

Check-in fields

asset_id (required), latitude, longitude, accuracy, photo_path, notes, created_at.

Environment Variables

Variable	Default	Description
CANTEEN_PORT	8901	Listen port
CANTEEN_DB_PATH	./assets.db	SQLite database path
CANTEEN_WIPE_DB	(empty)	Set to 1 to clear DB on start

Running Tests

pip install -r requirements.txt
python -m pytest tests/ -v

Project Structure

canteen-asset-tracker/
├── server.py          # FastAPI app (all routes, DB, error handling)
├── start.sh           # One-command startup with cert gen
├── static/
│   └── index.html     # SPA frontend (3 tabs + scanner)
├── tests/
│   └── test_server.py # 47 integration tests
├── uploads/           # Photo storage (gitignored)
├── cert.pem           # Self-signed TLS cert (auto-generated)
├── key.pem            # TLS private key (auto-generated)
├── requirements.txt   # Python deps
└── README.md