Initial commit: Canteen Asset Geolocation Tool v2

docs/FEATURES.md

@@ -0,0 +1,204 @@
+# Canteen Asset Tracker — Features Walkthrough
+
+> A mobile-friendly web app for tracking physical assets with barcode scanning, GPS check-ins, geofenced service areas, and technician assignment.
+
+![Login Screen](images/login.png)
+
+---
+
+## 1. 🔐 Authentication
+
+- **Login** with username/password
+- **Remember Me** persists session
+- Three roles: **Admin**, **Technician**, **readonly**
+- Default admin account: `admin` / `changeme`
+
+---
+
+## 2. 📷 Add Asset
+
+Three ways to add an asset:
+
+| Method | Description |
+|--------|-------------|
+| **Barcode** | Scan barcodes via device camera (ZXing library). Auto-lookup or prompt to create new. |
+| **OCR** | Upload a photo of a machine ID sticker; text is extracted via Tesseract OCR. |
+| **Manual** | Full form with all fields. |
+
+![Manual Entry Form](images/manual-entry.png)
+
+### Asset Fields
+
+- **Required:** Machine ID, Asset Name
+- **General:** Serial Number, Description, Category, Make, Model, Status
+- **Directions & Access:** Address/Trailer, Building name/number, Floor, Room, Walking directions, Map link (GPS pin), Parking location
+- **Keys:** Add named keys (MK300, Master Key, Padlock Key, etc.)
+- **Security Badges:** Checkboxes for badge types (Contractor, Employee, Visitor, etc.)
+- **Customer & Location:** Dropdowns for linked customer and location
+- **Photo:** Take or upload a photo of the asset
+
+---
+
+## 3. 📦 Asset List
+
+- Search by keyword or **Machine ID**
+- Filter by category, status, make
+- Sort by date, name, status
+- Tap any asset for full detail view, edit, or delete
+- **CSV Import** for bulk asset creation
+
+### Check-In History
+
+Each asset has a check-in timeline showing:
+- GPS coordinates (with map link)
+- Photo attachments
+- Notes from the technician
+- Timestamp
+
+---
+
+## 4. 🗺️ Map
+
+Interactive map powered by **Leaflet** + **OpenStreetMap** (free, no API key).
+
+![Map with Geofence](images/map-geofence.png)
+
+### Map Controls
+
+| Button | Action |
+|--------|--------|
+| 📍 **Pins** | Toggle asset location pins on/off |
+| 🔥 **Heatmap** | Toggle density heatmap of assets |
+| ✏️ **Add Geofence** | Enter draw mode to create polygons |
+| ◎ **My Location** | Center map on your GPS position |
+
+### Asset Pins
+
+- Each pin shows the asset name, machine ID, status, category
+- **Directions** link opens Google Maps navigation
+- **Details** button opens the full asset view
+- GPS blue dot shows your current location
+
+### Geofences (Service Areas)
+
+Draw polygons on the map to define service territories:
+
+- Custom colors per zone
+- **Point-in-polygon check** determines which zone contains a given GPS point
+- Each geofence can be assigned to one or more **technicians** (see §7)
+- Edit or delete existing geofences from the popup
+
+---
+
+## 5. 📊 Dashboard
+
+![Dashboard](images/dashboard.png)
+
+### Key Metrics
+- Total assets, total check-ins, active technicians
+
+### Breakdowns
+- **By Category** — Equipment, Furniture, Appliances, Utensils & Serveware, Other
+- **By Status** — Active, Maintenance, Retired
+- **By Make / Manufacturer** — see which brands you have most of
+- **Most Visited Assets** — top assets by check-in count
+
+### Quick Actions
+- **Assets CSV** — download full asset spreadsheet
+- **Check-ins CSV** — download check-in log
+- **Service Summary** — CSV report grouped by location/geofence
+- **Refresh** — reload dashboard data
+
+### Recent Activity Feed
+Live feed of creates, updates, and deletes across the system. Tap **View All** for the full activity log.
+
+---
+
+## 6. 📋 Reports
+
+- **Assets CSV Export** — all asset data with location, status, keys, badges
+- **Check-ins CSV Export** — history with GPS coordinates, timestamps, notes
+- **Service Summary** — company/location-based summary for billing or service records
+
+---
+
+## 7. 👤 Users & Service Areas
+
+### User Management (Settings → Users)
+- Create, edit, delete users
+- Set role: Admin, Technician, readonly
+- Each technician can be assigned to multiple geofence service areas
+
+### Assigning Users to Geofences
+
+From the **Map** tab:
+
+1. Tap an existing geofence polygon on the map
+2. Tap **👤 Assign** in the popup
+3. Check the technicians that cover this zone
+4. Save
+
+Or from the **Geofence List** (below the map):
+
+- Each zone shows an 👤 icon with user count
+- Tap **Assign** to open the same dialog
+
+### API Endpoint
+
+```
+GET /api/users/{user_id}/geofences
+```
+
+Returns all geofence service areas assigned to a specific user — useful for filtering assets or visits by a technician's territory.
+
+---
+
+## 8. ⚙️ Settings
+
+![Settings](images/settings.png)
+
+| Section | Description |
+|---------|-------------|
+| **Categories** | Manage asset categories (Appliances, Equipment, Furniture, etc.) |
+| **Makes & Models** | Manage manufacturers and their models |
+| **Key Names** | Key types for access (MK300, Master Key, Padlock Key, etc.) |
+| **Key Types** | Physical key types (Barrel, Flat, Standard, Tubular, etc.) |
+| **Security Badges** | Badge requirements (Contractor, Employee, Visitor, etc.) |
+| **Users** | Account management with role assignment |
+| **Theme** | Toggle between Dark and Light mode |
+| **Reset Database** | Wipe all data (admin only, requires confirmation) |
+
+---
+
+## 9. 🏢 Customers & Locations
+
+- **Customers** — company records with contact info
+- **Locations** — sites under each customer
+- **Rooms** — specific rooms/areas within locations
+- Hierarchical: Customer → Location → Room
+- Each asset can be linked to a customer and location
+
+---
+
+## 10. 📱 Mobile Features
+
+- **Responsive design** works on phones, tablets, and desktops
+- **Bottom navigation bar** for one-handed use
+- **Camera integration** for barcode scanning and OCR
+- **GPS auto-acquisition** for location-tagged check-ins
+- **Touch-friendly** form fields and buttons
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| **Backend** | FastAPI + SQLite (WAL mode) |
+| **Frontend** | Vanilla HTML/CSS/JS (single file, no build step) |
+| **Maps** | Leaflet 1.9.4 + OpenStreetMap |
+| **Geofences** | Leaflet Draw + point-in-polygon (Turf.js) |
+| **Scanner** | ZXing (CDN) |
+| **OCR** | Tesseract via pytesseract |
+| **TLS** | Self-signed cert on port 8901 |
+| **Reverse Proxy** | Nginx Proxy Manager Plus |

docs/USER_GUIDE.md

@@ -0,0 +1,364 @@
+# Canteen Asset Tracker — User Guide
+
+> A practical guide for technicians, supervisors, and admins using the Canteen Asset Tracker.
+
+## Table of Contents
+
+1. [Getting Started](#1-getting-started)
+2. [Logging In](#2-logging-in)
+3. [Adding an Asset](#3-adding-an-asset)
+4. [Checking In on an Asset](#4-checking-in-on-an-asset)
+5. [Finding Assets on the Map](#5-finding-assets-on-the-map)
+6. [Working with Geofences (Service Areas)](#6-working-with-geofences-service-areas)
+7. [Viewing Reports & Dashboard](#7-viewing-reports--dashboard)
+8. [Managing Users](#8-managing-users)
+9. [Settings & Configuration](#9-settings--configuration)
+10. [Tips & Troubleshooting](#10-tips--troubleshooting)
+
+---
+
+## 1. Getting Started
+
+### Accessing the App
+
+Open your phone or desktop browser and go to:
+
+```
+https://canteen.ourpad.casa:8901
+```
+
+> **On your phone:** The app is designed for mobile use — it fits your screen and works with touch controls.
+
+![Login Screen](images/login.png)
+
+### Browser Requirements
+
+- Any modern browser (Chrome, Firefox, Safari, Edge)
+- **Camera access** required for barcode scanning (grant when prompted)
+- **Location/GPS** required for check-in location tagging (grant when prompted)
+- Accept the self-signed certificate warning (it's safe — the cert is auto-generated)
+
+---
+
+## 2. Logging In
+
+### Default Credentials
+
+| Role | Username | Password |
+|------|----------|----------|
+| Admin | `admin` | `changeme` |
+
+**⚠️ Change the default password immediately** via Settings → Users → Edit.
+
+### Login Screen
+
+1. Enter your **Username**
+2. Enter your **Password**
+3. Check **Remember me** to stay logged in
+4. Tap **Sign In**
+
+### User Roles
+
+| Role | Permissions |
+|------|-------------|
+| **Admin** | Full access — create/edit/delete everything, manage users |
+| **Technician** | Add assets, check in, view maps and geofences |
+| **readonly** | Read-only — browse assets, view dashboard and reports |
+
+---
+
+## 3. Adding an Asset
+
+Tap the **📷 Add Asset** tab (bottom nav bar or drawer menu).
+
+You have three methods:
+
+### Option A: Barcode Scan
+
+1. Tap the **📷 Barcode** tab
+2. Point your camera at the asset's barcode
+3. If the barcode exists → asset details load
+4. If new → you're prompted to create the asset with the scanned barcode
+
+### Option B: OCR (Photo of Machine ID)
+
+1. Tap the **🔍 OCR** tab
+2. Take a photo of the machine ID sticker
+3. The app extracts the ID number automatically
+4. Confirm and fill in remaining details
+
+### Option C: Manual Entry
+
+Tap **✏️ Manual** and fill out the form:
+
+**Required fields:**
+- **Machine ID** — unique identifier (often found on a sticker)
+- **Asset Name** — descriptive name (e.g., "Walk-In Cooler")
+
+![Manual Entry Form](images/manual-entry.png)
+
+**Optional details:**
+- Serial Number, Description
+- **Category** — Equipment, Furniture, Appliances, etc.
+- **Make** — brand/manufacturer
+- **Model** — specific model
+- **Status** — Active, Maintenance, Retired
+
+**📍 Directions & Access** — critical for finding the asset later:
+- Address / Trailer Number
+- Building name and number
+- Floor and Room
+- Walking directions (e.g., "Enter through loading dock, go left")
+- Map link or tap **Pin** to drop a GPS pin
+- Parking location
+
+**🔑 Keys needed:**
+Tap **+ Add Key** to record which keys are required (e.g., MK300, Master Key, Padlock Key)
+
+**🪪 Security Badges:**
+Check which badges are required for access (Contractor, Employee, Visitor, etc.)
+
+**🏢 Customer & Location:**
+Select the customer and site location from dropdowns.
+
+**📸 Photo:**
+Tap the camera area to take a photo of the asset.
+
+### Save
+
+- **Create Asset** — saves and stays on the form
+- **+ Add Another** — saves and clears the form for the next asset
+
+---
+
+## 4. Checking In on an Asset
+
+### From the Asset Detail View
+
+1. Tap **📦 Asset List**
+2. Search or browse to find the asset
+3. Tap on the asset row to open details
+4. Tap **Check In**
+5. Your GPS location is captured automatically
+6. Optionally add notes or a photo
+7. Tap **Submit**
+
+### Via the Dashboard
+
+- The **Recent Activity** feed shows the latest check-ins
+- Tap any check-in entry to see details
+
+---
+
+## 5. Finding Assets on the Map
+
+Tap the **🗺️ Map** tab.
+
+![Map with Geofence](images/map-geofence.png)
+
+### Toggle Layers
+
+| Button | What it does |
+|--------|-------------|
+| 📍 **Pins** | Show/hide asset location pins on the map |
+| 🔥 **Heatmap** | Show/hide a color heatmap of asset density |
+| ✏️ **Add Geofence** | Start drawing a service area polygon |
+| ◎ **My Location** | Center the map on your current GPS position |
+
+### Using Asset Pins
+
+- Each pin represents an asset with GPS coordinates
+- **Tap a pin** to see: asset name, machine ID, status, category
+- **Directions** — opens Google Maps navigation to that asset
+- **Details** — opens the full asset record
+
+### Getting Directions
+
+1. Find the asset on the map (or in Asset List → Details)
+2. Tap **Directions** or the map link
+3. Google Maps opens with the asset as the destination
+
+---
+
+## 6. Working with Geofences (Service Areas)
+
+Geofences let you draw **service zones** on the map and assign **technicians** to cover each zone.
+
+### Creating a Geofence
+
+1. Tap the **🗺️ Map** tab
+2. Tap **✏️ Add Geofence**
+3. Tap points on the map to draw a polygon around your service area
+4. Tap the last point to close the shape
+5. Name the zone (e.g., "Downtown Orlando", "Building A")
+6. Choose a color
+7. Tap **Save**
+
+### Viewing Geofences
+
+- Saved geofences appear as colored polygons on the map
+- Tap a polygon to see the zone name and assigned users
+
+### Assigning Users to a Geofence
+
+Assigning a technician to a geofence means that zone is **their service area**.
+
+1. Tap a geofence polygon on the map
+2. In the popup, tap **👤 Assign**
+3. A dialog shows all users with checkboxes
+4. Check the technicians who cover this zone
+5. Tap **Save**
+
+Or from the geofence list (below the map):
+- Each zone shows an 👤 badge with the number of assigned users
+- Tap **Assign** to open the same dialog
+
+### Removing User Assignment
+
+Same process — uncheck a user and save. The user is removed from that service area.
+
+### Listing a User's Service Areas
+
+To see all zones a technician is assigned to:
+
+```
+GET /api/users/{user_id}/geofences
+```
+
+This returns every geofence the user is assigned to — useful for filtering work orders by territory.
+
+---
+
+## 7. Viewing Reports & Dashboard
+
+### Dashboard
+
+Tap the **📊 Dash** tab to see:
+- **Total Assets** count
+- **Total Check-ins** count
+- **Active Technicians** count
+
+![Dashboard](images/dashboard.png)
+
+- Breakdowns by category, status, and manufacturer
+- **Most Visited Assets** ranking
+- **Recent Activity** feed
+- **Quick Actions** for CSV exports
+
+### Exporting Reports
+
+From the Dashboard, tap:
+
+| Button | What you get |
+|--------|-------------|
+| 📋 **Assets CSV** | All assets with location, status, keys, badges |
+| 📍 **Check-ins CSV** | Check-in history with GPS, timestamps, notes |
+| 📊 **Service Summary** | Report grouped by customer/location |
+
+CSV files download to your device and can be opened in Excel, Google Sheets, or any spreadsheet app.
+
+### Reports Tab
+
+The **📋 Reports** tab has additional export options and filterable reports.
+
+---
+
+## 8. Managing Users
+
+### Adding a User
+
+1. Tap **⚙️ Settings** (from drawer menu)
+2. Scroll to the **Users** section
+3. Tap **+ Add**
+4. Enter: Username, Password, Display Name, Role
+5. Tap **Save**
+
+### Editing a User
+
+1. Tap the **✏️** (edit) button next to the user
+2. Update fields
+3. Tap **Save**
+
+### Deleting a User
+
+1. Tap the **🗑️** (delete) button next to the user
+2. Confirm deletion
+3. The user is removed from the system and all geofence assignments are cleaned up automatically
+
+> **Note:** Deleting a user also removes their geofence assignments (cascade delete). It does NOT delete assets or check-ins created by that user.
+
+---
+
+## 9. Settings & Configuration
+
+### Managing Dropdown Lists
+
+In **⚙️ Settings** you can add, edit, or delete values for:
+
+![Settings](images/settings.png)
+
+| List | Example Values |
+|------|---------------|
+| **Categories** | Equipment, Furniture, Appliances, Utensils & Serveware, Other |
+| **Makes** | Cambro, Hobart, Metro, Rubbermaid, Vollrath |
+| **Models** | Specific models under each make |
+| **Key Names** | MK300, Master Key, Padlock Key, Red Key, Green Dot |
+| **Key Types** | Barrel, Flat, Standard, Tubular, Round Short |
+| **Security Badges** | Employee Badge, Contractor Badge, Visitor Badge |
+
+### Changing Theme
+
+Tap the **Theme** dropdown in Settings to switch between:
+- **Dark** (default) — easier on the eyes in low-light
+- **Light** — better in bright environments
+
+### Resetting the Database
+
+> ⚠️ **Warning:** This permanently deletes ALL data — assets, check-ins, geofences, users, everything.
+
+1. Go to **⚙️ Settings**
+2. Scroll to the bottom
+3. Tap **🗑 Reset Database** (red button)
+4. Confirm by typing "DELETE" in the prompt
+5. Tap **Confirm**
+
+The app will restart with fresh default data (admin account and example settings).
+
+---
+
+## 10. Tips & Troubleshooting
+
+### Common Issues
+
+| Problem | Solution |
+|---------|----------|
+| **Can't log in** | Check caps lock. Passwords are case-sensitive. Ask an admin to reset your password. |
+| **Camera not working** | Grant camera permission when prompted. On iPhone, check Settings → Safari → Camera. |
+| **GPS not working** | Grant location permission. On Android, use "While using the app" not "Deny". |
+| **Map tiles not loading** | Check your internet connection. OpenStreetMap tiles require internet access. |
+| **"User denied Geolocation"** | Refresh the page and allow location when prompted. |
+| **Barcode won't scan** | Ensure good lighting. Hold the phone 4-8 inches from the barcode. Try the manual entry instead. |
+| **502 Bad Gateway** | The server may be restarting. Wait 30 seconds and refresh. |
+
+### Best Practices
+
+- **Add photos** — a picture of the asset saves time for the next technician
+- **Be specific with directions** — "Behind the walk-in cooler, third shelf from the top" is better than "In the back"
+- **Record key info** — note which keys and badges are needed before you go
+- **Check in every visit** — this builds the service history and helps with billing
+- **Assign geofences** — when a technician joins, assign their service areas so route planning is clear
+
+### Keyboard Shortcuts (Desktop)
+
+- **Esc** — Close modals / dialogs
+- **Enter** — Submit forms
+- **Menu** → click away — Close drawer
+
+### Offline / Low Connectivity
+
+The app requires an internet connection to load data. If connectivity is poor:
+1. Load the page while connected
+2. Navigate to the data you need (it stays in browser memory)
+3. Don't refresh until you're back online
+
+For full offline support, use the **Android app** which caches data locally.