Initial commit: Canteen Asset Geolocation Tool v2

2026-05-17 18:55:28 -04:00
commit 7da3f28c6a
50 changed files with 19509 additions and 0 deletions
@@ -0,0 +1,130 @@
+# Canteen Asset Tracker — Project Structure
+
+Two projects, one API contract.
+
+## Repositories
+
+```
+~/projects/canteen-asset-tracker/           ← Web app (Python/FastAPI backend + SPA frontend)
+~/projects/canteen-asset-tracker-android/   ← Android app (Kotlin, Jetpack Compose)
+```
+
+## Web App (`canteen-asset-tracker`)
+
+```
+canteen-asset-tracker/
+├── server.py              FastAPI backend — all 78 API routes + DB logic
+├── openapi.yaml           **Shared API contract** — source of truth for both projects
+├── assets.db              SQLite database (WAL mode, foreign keys on)
+├── static/
+│   └── index.html         Single-page frontend (276 KB, self-contained)
+├── tests/                 pytest test suite (319 tests)
+├── uploads/               User-uploaded photos/icons
+├── cert.pem / key.pem     Self-signed TLS certs
+├── requirements.txt       Python deps (fastapi, uvicorn, pytesseract, pillow)
+├── start.sh               Launch script (production)
+└── smoke_test.sh          Smoke test suite
+```
+
+- **Port:** 8901 (HTTPS)
+- **URL:** https://canteen.ourpad.casa:8901
+- **Frontend:** Single HTML file — no build step, no npm. All JS/CSS/HTML in one file.
+- **Backend:** FastAPI with SQLite (WAL mode). 48 named routes + 30 dynamic settings routes.
+- **Tests:** 319 backend tests passing. No frontend tests yet.
+
+## Android App (`canteen-asset-tracker-android`)
+
+```
+canteen-asset-tracker-android/
+├── app/
+│   ├── src/main/java/com/canteen/assettracker/
+│   │   ├── network/
+│   │   │   └── RetrofitModule.kt   API client config (points to web app URL)
+│   │   ├── ui/
+│   │   │   ├── login/              Login screen + ViewModel
+│   │   │   ├── dashboard/          Dashboard screen + ViewModel
+│   │   │   └── settings/           Settings screen + ViewModel
+│   │   └── location/
+│   │       └── ProximityEngine.kt  GPS proximity logic
+│   └── build/                      Build outputs (APK, test reports)
+├── build.gradle.kts                Root build config
+├── settings.gradle.kts
+├── gradlew / gradlew.bat           Gradle wrapper
+└── keystore.properties             Signing keys
+```
+
+- **Package:** `com.canteen.assettracker`
+- **API Base URL:** `https://canteen.ourpad.casa:8901/` (hardcoded in `RetrofitModule.kt`)
+- **Tests:** 3 ViewModel/engine test classes, all passing (debug + release)
+- **Built APK:** run `./gradlew assembleRelease`
+
+## API Contract
+
+`openapi.yaml` is the **single source of truth**. When you change the backend:
+
+1. Update `server.py`
+2. Update `openapi.yaml` to match
+3. Android team (or future-you) can see exactly what changed
+
+The spec covers:
+- **48 named routes** across assets, check-ins, customers, locations, rooms, users, auth, geofences, visits, activity, stats, exports, uploads, and OCR
+- **30 dynamic settings routes** (`/api/settings/{entity}` for 6 entity types)
+- All request/response schemas
+- Query parameters and path parameters
+
+### Quick reference — main route groups
+
+| Group      | Routes                        |
+|------------|-------------------------------|
+| Auth       | login, me                     |
+| Assets     | CRUD + search by machine ID   |
+| Check-ins  | CRUD (GPS + photo + notes)    |
+| Customers  | CRUD with contacts            |
+| Locations  | CRUD + child rooms            |
+| Rooms      | CRUD (nested under locations) |
+| Users      | CRUD                          |
+| Geofences  | CRUD + user assignment (service areas) |
+| Visits     | CRUD + stats                  |
+| Stats      | Dashboard aggregates          |
+| Exports    | Assets CSV, Check-ins CSV, Service Summary CSV |
+| Uploads    | Icon + Photo upload           |
+| OCR        | Extract machine ID from sticker image |
+| Settings   | Dynamic CRUD for 6 entity types |
+| Proximity  | Find assets near GPS point    |
+| Activity   | Activity feed                 |
+
+## Working with both projects
+
+### Adding a feature to BOTH web + Android
+1. Design the endpoint in `openapi.yaml` first
+2. Implement in `server.py`
+3. Run backend tests
+4. Implement Android client code + run Android tests
+
+### Adding a feature to web ONLY
+1. Add endpoint to `server.py`
+2. Update `openapi.yaml`
+3. Android app ignores the new endpoint — no changes needed
+
+### Adding a feature to Android ONLY
+1. Plan the endpoint in `openapi.yaml` (even if backend isn't ready)
+2. Build Android client against the planned contract
+3. Backend implements later
+
+## Running
+
+```bash
+# Web app
+cd ~/projects/canteen-asset-tracker
+./start.sh                          # production
+# or: uvicorn server:app --reload   # development
+
+# Tests
+cd ~/projects/canteen-asset-tracker
+python -m pytest tests/ -v
+
+# Android
+cd ~/projects/canteen-asset-tracker-android
+./gradlew assembleRelease           # build APK
+./gradlew test                      # run unit tests
+```