Document modifier template system, virtual IDs, and clean API key names in CLAUDE.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -168,12 +168,9 @@ Production:
 
 ## Database
 
-- **Production**: `payfrit` on db.payfrit.com (still uses OLD prefixed column names)
+Both `payfrit` (production) and `payfrit_dev` (development) use **clean, unprefixed column names**. PKs are always `ID`. FKs reference their parent table (e.g., `BusinessID`, `UserID`).
-- **Development**: `payfrit_dev` on db.payfrit.com (migrated to clean names)
 
-**Dev DB uses clean, unprefixed names.** PKs are always `ID`. FKs reference their parent table (e.g., `BusinessID`, `UserID`). No table-name prefixes on columns.
+Key tables:
-
-Key tables (dev schema):
 
 | Table | PK | Key Columns |
 |-------|----|-------------|
@@ -187,6 +184,35 @@ Key tables (dev schema):
 | ServicePoints | `ID` | `BusinessID`, `Name`, `TypeID`, `Code`, `SortOrder`, `IsActive`, `BeaconID` |
 | Beacons | `ID` | `BusinessID`, `UUID`, `Name`, `IsActive` |
 | Menus | `ID` | `BusinessID`, `Name`, `IsActive` |
+| Employees | `ID` | `BusinessID`, `UserID`, `StatusID`, `RoleID`, `IsActive` |
+| tt_StaffRoles | `ID` | `Name` (1=Staff, 2=Manager, 3=Admin) |
+| lt_ItemID_TemplateItemID | — | `ItemID`, `TemplateItemID`, `SortOrder` |
+
+## Modifier Template System (IMPORTANT)
+
+Modifier groups can be shared across multiple menu items via the **template linking table** `lt_ItemID_TemplateItemID`. A template is a top-level Item (`ParentItemID=0`, `CategoryID=0`) with child options. Menu items link to templates via the linking table, not via `ParentItemID`.
+
+Example: "Cheeseburger Mods" (template) → children: "SIDE AVOCADO", "NO CHEESE", etc. Both CHEESEBURGER and DOUBLE CHEESEBURGER link to the same template.
+
+### Virtual IDs in items.cfm
+
+`items.cfm` returns template-linked modifiers as **virtual children** of menu items with synthetic IDs:
+
+- **Template group**: `virtualID = menuItemID * 100000 + templateItemID`
+- **Template option**: `virtualID = menuItemID * 100000 + optionItemID`
+- **ParentItemID** is set to `menuItemID` (for template groups) or `virtualTemplateID` (for options)
+
+This makes templates appear as regular children in the item tree. Mobile apps see them in `itemsByParent[menuItemId]` alongside any direct children.
+
+### Virtual ID Decoding in setLineItem.cfm
+
+When receiving virtual IDs from clients: `realItemID = virtualID MOD 100000` (if ItemID > 100000).
+
+**CRITICAL**: API responses always return **real** ItemIDs, not virtual IDs. Clients must account for this round-trip: virtual IDs go out, real IDs come back.
+
+### API Response Key Names
+
+All API endpoints use **clean key names** matching the database columns (e.g., `ItemID`, `ParentOrderLineItemID`, `Price`). Do NOT use old prefixed key names like `OrderLineItemItemID` — those are legacy and will cause key mismatches in client parsers.
 
 ## Order Status Flow