From c4580b6fd18c5c3efff3c6bf11e6fd44856873aa Mon Sep 17 00:00:00 2001
From: Shawn <shawn@ourpad.casa>
Date: Sun, 31 May 2026 00:32:22 -0400
Subject: [PATCH] docs: add Category Icon System documentation

---
 Category-Icon-System.md | 54 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 Category-Icon-System.md

diff --git a/Category-Icon-System.md b/Category-Icon-System.md
new file mode 100644
index 0000000..1369358
--- /dev/null
+++ b/Category-Icon-System.md
@@ -0,0 +1,54 @@
+# Category Icon System
+
+The Canteen Asset Tracker uses a category-based icon system to visually identify asset types at a glance.
+
+## Category Map (main app `static/index.html`)
+
+| Category   | Icon | Color    |
+|------------|------|----------|
+| Bev        | 🥤   | #0a7ab5 |
+| Snack      | 🍿   | #c97d0e |
+| Food       | 🍔   | #e67e22 |
+| Equipment  | 🔧   | #2c3e50 |
+| Appliances | 🔌   | #3b82f6 |
+| Other      | 📦   | #6b7280 |
+
+## Fallback Logic (`categoryInfo()`)
+
+- Category in map → uses that entry's icon + color
+- Category exists but NOT in map (unmapped) → ❓ with red background (#b91c1c) — visible signal to admin
+- Null/missing category → 📦 (generic)
+
+This means any new category imported from Cantaloupe that isn't in the lookup table will immediately be visible as ❓ on the technician's phone, prompting the admin to add it.
+
+## Admin Server Category Health
+
+The `/api/stats` endpoint includes `category_health`:
+```json
+{
+  "unmapped": [{"name": "Snack/Bev", "count": 18}],
+  "total_categories": 6,
+  "unmapped_count": 1
+}
+```
+
+The admin dashboard shows a red **⚠️ Category Health** card when `unmapped_count > 0`, linking to Settings → Categories to fix.
+
+## DB Schema
+
+Table `categories`:
+- `id` INTEGER PRIMARY KEY
+- `name` TEXT UNIQUE NOT NULL
+- `icon` TEXT (emoji or image path)
+
+Seed data (both `server.py` and `admin_server.py`):
+```python
+("Bev", "🥤"), ("Snack", "🍿"),
+("Food", "🍔"), ("Equipment", "🔧"),
+("Appliances", "🔌"), ("Other", "📦"),
+```
+
+## History
+
+- **2026-05-29 (f1a3bb9):** Cleaned CATEGORY_MAP (removed dead entries, fixed duplicates). Added `categoryInfo()` helper with proper unmapped fallback. Added detail view icons. Synced DB categories with real asset data.
+- **Admin d58834b:** Added Category Health dashboard widget.