canteen-asset-tracker/docs/ADMIN_GUIDE.md

Canteen Admin Panel — User Guide

Administrative interface for managing customers, locations, users, geofences, settings, and Excel data imports. Designed for desktop but mobile-responsive with a hamburger menu on phones (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. Excel Import
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

Mobile Navigation

On phones, the sidebar is hidden behind a ☰ hamburger button. Tap it to slide the navigation in from the left. The sidebar auto-closes when you tap a nav item or tap the dark overlay behind it.

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
• 📥 Import — Cantaloupe Excel 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. Excel Import

Navigate to 📥 Import in the sidebar.

The Import page lets you upload asset data from Excel files.

How it Works

1. Click 📤 Upload Excel and select your .xlsx or .xls file
2. The system parses the file, maps columns, and creates a pending import batch
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 if the data looks wrong

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

Import Fails

1. Make sure your Excel file has a header row and at least one data row
2. The system maps columns by keyword matching — check that column headers contain recognizable terms like "Asset ID", "Name", etc.
3. Check the error message displayed after upload
4. Try exporting from Cantaloupe to Excel first, then upload the file manually

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.