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