canteen-asset-tracker/docs/USER_GUIDE.md

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
2. Logging In
3. Adding an Asset
4. Checking In on an Asset
5. Finding Assets on the Map
6. Working with Geofences (Service Areas)
7. Viewing Reports & Dashboard
8. Tips & Troubleshooting

---

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.

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

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.

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

---

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:

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.

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!