canteen-asset-tracker/docs/ADMIN_GUIDE.md

Canteen Admin Panel — User Guide

Administrative interface for managing customers, locations, users, geofences, settings, and Cantaloupe data sync. Designed for desktop but mobile-responsive (screenshots from Pixel 9a).

Table of Contents

1. Accessing the Admin Panel
2. Dashboard Overview
3. Managing Customers & Locations
4. Managing Users
5. Geofences (Service Areas)
6. Settings & Configuration
7. Cantaloupe Data Sync
8. Activity Log & Reports
9. Tips & Troubleshooting

---

1. Accessing the Admin Panel

Open your browser and go to:

https://admin.canteen.ourpad.casa

Logging In

Use the same credentials as the main app:

Role	Username	Password
Admin	admin	changeme

---

2. Dashboard Overview

After logging in, the dashboard shows:

• Total Assets count
• Total Check-ins count
• Active Users count
• Recent Activity feed
• Quick access to all management sections via the sidebar

Sidebar Navigation

The sidebar on the left provides access to:

• 📊 Dashboard — Stats overview and activity feed
• 🏢 Customers — Customer and location management
• 👥 Users — User account management
• 📍 Geofences — Service area polygon management
• 🔄 Sync — Cantaloupe data import
• ⚙️ Settings — Categories, makes, models, key types, badge types
• 📋 Activity — Full activity log with filters
• 📤 Exports — CSV data export

---

3. Managing Customers & Locations

Customers

The Customers page shows a searchable list of all customers.

Add a Customer:

1. Click + Add Customer
2. Enter the customer's name
3. Optionally add contacts (name, phone, email)
4. Click Save

Edit/Delete: Use the ✏️ and 🗑 buttons next to each customer.

Locations

Within each customer's detail view, you can add locations:

• Click on a customer to expand their details
• + Add Location — Add a new site/building
• Location fields: name, address, building name, floor, site hours, trailer number, access notes, walking directions, GPS coordinates

---

4. Managing Users

Navigate to 👥 Users in the sidebar.

Add a User:

• Click + Add User
• Enter username, password, and select a role (admin / technician / readonly)
• Techs can create assets and check-ins; readonly users can only view

---

5. Geofences (Service Areas)

Navigate to 📍 Geofences in the sidebar.

• + Add Geofence — Draw a polygon on the map to define a service area
• Assign geofences to specific users/technicians
• Edit or delete existing geofences

Geofences appear as colored polygons on the main app's map for visual reference.

---

6. Settings & Configuration

Navigate to ⚙️ Settings in the sidebar.

Manage these lookup tables:

• Categories — Asset categories (Appliances, Furniture, etc.)
• Makes — Manufacturer names (Canteen, Hobart, Vollrath, etc.)
  • Expand each make to manage its Models
• Key Names — Field service key names
• Key Types — Field service key types
• Badge Types — Asset badge types

---

7. Cantaloupe Data Sync

Navigate to 🔄 Sync in the sidebar.

The Cantaloupe Sync page lets you import asset data from the Cantaloupe vending management system.

How it Works

1. Sync Now button — Downloads the latest Excel export from Cantaloupe and creates a pending import batch
2. Upload Excel File — Manually upload a Cantaloupe Excel export file
3. Review Changes — Each batch shows new, changed, and removed assets with field-level diffs
4. Approve — Apply the changes to live data
5. Reject — Discard the batch

Import History

The bottom section shows all past import batches with their status (PENDING / APPROVED / REJECTED / ERROR) and change summaries.

---

8. Activity Log & Reports

Activity Log

Navigate to 📋 Activity in the sidebar.

• Full chronological log of all actions (creates, updates, deletes, check-ins, logins)
• Filters: by user, action type, date range
• Uses pagination for large logs

CSV Exports

Available at the bottom of the sidebar:

• Export Assets — Download all assets as CSV
• Export Check-ins — Download check-ins filtered by asset

Database Reset

⚠️ Danger zone: The Reset Database button in the sidebar footer deletes ALL data and reinitializes with defaults. Requires confirmation.

---

9. Tips & Troubleshooting

Cantaloupe Sync Fails

1. Check the credentials in the Cantaloupe downloader config
2. The server must have network access to mycantaloupe.com
3. Check the error message in the sync batch detail view
4. Try the Upload Excel File option as a fallback

Admin Panel Not Loading

• Hard refresh (Ctrl+Shift+R on desktop, long-press refresh on mobile)
• Clear site data
• Check that both services are running (canteen-main.service and canteen-admin.service)

Permissions

• You must be logged in as an admin role user to access the admin panel
• Technicians and readonly users cannot access the admin panel
• Session tokens expire after 1 day (or 30 days with "Remember me")

---

Note: The admin panel shares the same database as the main app, so changes made here (customers, locations, geofences, settings) are immediately visible in the field app.