# Canteen Asset Tracker — User Guide

> A practical guide for technicians, supervisors, and admins using the Canteen Asset Tracker on mobile (Pixel 9a shown).

## 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. [Tips & Troubleshooting](#8-tips--troubleshooting)
9. [Admin Panel](#9-admin-panel)

---

## 1. Getting Started

### Accessing the App

Open your phone or desktop browser and go to:

```
https://canteen.ourpad.casa
```

> **On your phone:** The app is designed for mobile use — it fits your screen and works with touch controls. Pixel 9a viewport shown in screenshots.

![Login Screen](images/p9a_main_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)

---

## 2. Logging In

### Default Credentials

| Role | Username | Password |
|------|----------|----------|
| Admin | `admin` | `changeme` |

### Steps

1. Open https://canteen.ourpad.casa in your browser
2. Tap **Username** and enter your username
3. Tap **Password** and enter your password
4. Check **Remember me** if you want to stay logged in for 30 days
5. Tap **Sign In**

![Login Screen](images/p9a_main_login.png)

### After Login

Once logged in, you'll see the main dashboard. The default view shows the **Add Asset** tab with options for barcode scanning, OCR, or manual entry.

![Dashboard](images/p9a_main_dashboard.png)

### Navigation

The bottom tab bar gives you quick access to:
- **➕ Add** — Add a new asset via barcode, OCR, or manual form
- **📋 Assets** — Browse and search all assets
- **🗺️ Map** — View assets on the map with geofences and heatmap
- **🧭 Nav** — Navigation tools
- **⋯ More** — Open the drawer for Settings, Reports, and Logout

![Drawer Menu](images/p9a_main_drawer.png)

---

## 3. Adding an Asset

The app offers three ways to add an asset:

### Option A: Barcode Scan (fastest)

1. Tap the **Barcode** toggle on the Add Asset tab
2. Tap **Tap to start camera** and grant camera permission
3. Point the camera at the asset's barcode sticker
4. The scanner auto-detects the barcode and fills in the machine ID
5. Confirm the details and tap **Create Asset**

### Option B: OCR (photo of label)

1. Tap the **OCR** toggle
2. Tap **Take Photo** or **Pick Photo** to capture the asset's label
3. The app extracts the machine ID using text recognition
4. Review and correct if needed, then tap **Create Asset**

### Option C: Manual Entry

Tap **Manual** to fill in all fields by hand:

![Manual Entry Form](images/p9a_main_manual_form.png)

Fields:
- **Machine ID** — The asset's unique ID (required)
- **Name** — A descriptive name (required)
- **Category** — e.g. Appliances, Furniture, Electronics
- **Status** — active, maintenance, retired
- **Serial Number** — Optional
- **Make / Model** — Optional
- **Address / Location Info** — Where the asset is located
- **GPS Coordinates** — Tap the 📍 button to auto-fill your current location
- **Photo** — Optional, upload an image of the asset
- **Notes** — Any additional information

---

## 4. Checking In on an Asset

1. From the **Assets** list, tap an asset to open its detail view
2. Tap **Check In**
3. The app captures your GPS location automatically
4. Add any notes about the visit
5. Tap **Submit Check-in**

Each check-in creates a **Visit** record, which is used for service tracking and reporting.

---

## 5. Finding Assets on the Map

Tap the **🗺️ Map** tab to view all assets plotted on an interactive map.

![Map View](images/p9a_main_map.png)

Features:
- **Blue pins** mark asset locations
- **Toggle Pins** button shows/hides asset markers
- **Heatmap** view shows asset density
- **🎯 My GPS** button centers the map on your location (requires GPS permission)
- Tap a pin to see asset details and get directions

The map is powered by **Leaflet** with **OpenStreetMap** tiles — no API key needed.

---

## 6. Working with Geofences (Service Areas)

Geofences are managed from the **admin panel** (see Admin Guide). Once created, they appear on the main app's map as colored polygons:

- Tap a geofence polygon to see its name and details
- Geofences help organize assets by service area or route

---

## 7. Viewing Reports & Dashboard

The Dashboard tab shows:
- **Total assets** and **total check-ins** counts
- **Recent activity** feed showing who did what
- **Category and status breakdowns**

Access the drawer menu (**⋯ More**) → **Dashboard** for a full view.

---

## 8. Tips & Troubleshooting

### GPS Not Working

- Tap the **📍 Tap for GPS** badge in the top header (it prompts the permission)
- If prompted, tap **Allow** on the browser's location permission dialog
- On Pixel 9a / Android: ensure Location is enabled in Quick Settings
- If GPS still doesn't work, open browser settings → Site Settings → Location → Allow

### Camera Not Working

- Ensure you're on **HTTPS** (camera requires a secure connection)
- Grant camera permission when prompted by the browser
- Try the **Pick Photo** option instead — it uses the gallery and may work better on some browsers

### Barcode Not Scanning

- Ensure good lighting on the barcode
- Hold the camera steady about 4-6 inches from the label
- Try **OCR** mode if the barcode is damaged or smudged

### Login Issues

- Check your username and password
- Use the **admin / changeme** default credentials if they haven't been changed
- Contact your supervisor for password resets

### App Not Loading / Blank Page

- Hard refresh: long-press the browser refresh icon → **Bypass Cache**
- Clear site data: browser settings → Site Settings → Clear data
- If the problem persists, the server may be down — contact IT support

---

> **Pro tip:** For the best mobile experience, add the app to your home screen:
> Chrome → Menu → **Add to Home Screen**. It opens like a native app!

---

## 9. Admin Panel

The **Admin Panel** at [admin.canteen.ourpad.casa](https://admin.canteen.ourpad.casa) provides management tools for:

- **Dashboard** — Overview of all assets, check-ins, customers, and users
- **Settings** — Manage categories, makes/models, key types, badge types
- **Users** — Create and manage user accounts with role-based access
- **Customers** — Manage customer accounts and locations
- **Activity Log** — Full audit trail with filters and pagination
- **Export** — Export asset and check-in data as CSV
- **Import** — Upload Excel files to import asset data

![Admin Dashboard](images/p9a_admin_dashboard.png)

> See the **[Admin Guide](ADMIN_GUIDE.md)** for full documentation.
