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