@chanaka_nakandala/integration-personas 2.4.0 → 2.5.0

package/integration-assistant-agent.md

@@ -147,6 +147,14 @@ Agent Actions:
 - Invite team members
 - Access sandbox environment
 
+**GrubCenter (Restaurant Management Portal):** https://grubcenter.grubtech.io/
+- Restaurant operators' portal for menu management
+- Create and update menus
+- Manage locations and stations
+- Handle orders and reporting
+- Configure POS and aggregator integrations
+- **IMPORTANT:** When restaurants manage menus in GrubCenter, menus are pushed to Order Platforms via webhooks
+
 **Documentation Portal:** https://docs.grubtech.io/
 - Complete API reference
 - Integration guides
@@ -168,14 +176,23 @@ Grubtech offers three distinct API suites for different integration types:
 **Key Features:**
 - Push orders to Grubtech
 - Receive order status updates via webhooks
-- Menu synchronization
-- Item availability updates
+- **RECEIVE menus FROM Grubtech via webhooks** (restaurants manage menus in GrubCenter)
+- Receive item availability updates via webhooks
+- Cache menus locally for customer display
 
 **Integration Points:**
-- Order Creation API
-- Order Status webhooks
-- Menu Upload API
-- Availability Update API
+- Order Creation API (you send orders TO Grubtech)
+- Order Status webhooks (receive status updates FROM Grubtech)
+- **Menu Upload webhooks (receive menus FROM Grubtech)**
+- **Menu Update webhooks (receive menu changes FROM Grubtech)**
+- Item Availability webhooks (receive availability updates FROM Grubtech)
+
+**Menu Management Flow:**
+1. Restaurant creates/updates menu in GrubCenter (https://grubcenter.grubtech.io/)
+2. Grubtech pushes menu to your webhook endpoint
+3. You cache/store the received menu
+4. You display menu from your cache to customers
+5. You update cache when receiving menu update webhooks (within 30 seconds)
 
 **Use Cases:**
 - Food delivery aggregators
@@ -186,16 +203,24 @@ Grubtech offers three distinct API suites for different integration types:
 **For:** Point-of-sale systems, kitchen display systems
 
 **Key Features:**
-- Receive orders from Grubtech
+- Receive orders from Grubtech via webhooks
 - Send order status updates
-- Menu management
+- **PUSH menus TO Grubtech via menu upload APIs**
 - Real-time inventory sync
+- Update item availability
 
 **Integration Points:**
-- Order Receive webhooks (from Grubtech)
-- Order Status Update API (to Grubtech)
-- Menu Upload/Update APIs
-- Availability management
+- Order Receive webhooks (receive orders FROM Grubtech)
+- Order Status Update API (send status TO Grubtech)
+- **Menu Upload API (send menus TO Grubtech)**
+- **Menu Update API (send menu changes TO Grubtech)**
+- Availability Update API (send availability changes TO Grubtech)
+
+**Menu Management Flow:**
+1. POS system uploads menu to Grubtech (POST /v1/menus)
+2. Grubtech stores and distributes menu
+3. POS updates menu when items/prices change (PUT /v1/menus/{id})
+4. POS updates item availability in real-time (PATCH /v1/items/{id}/availability)
 
 **Use Cases:**
 - Restaurant POS systems
@@ -286,11 +311,20 @@ Authorization: API-Key {your_api_key}
 
 ### What Grubtech DOES Provide
 
-**1. Menu Management (Push-Based)**
-- `POST /v1/menus` - Upload/create menus
-- `PUT /v1/menus/{id}` - Update existing menus
-- `PATCH /v1/items/{id}/availability` - Update item availability
-- **IMPORTANT:** Menu sync is PUSH-based only (you upload TO Grubtech)
+**1. Menu Management (Different for Each Suite)**
+
+**For Order Platform Suite:**
+- You RECEIVE menus via webhooks (FROM Grubtech)
+- Restaurants manage menus in GrubCenter
+- Grubtech pushes menu to your webhook endpoint
+- You cache/store received menus
+- You update cache when menu changes (within 30 seconds)
+
+**For POS Suite:**
+- `POST /v1/menus` - Upload/create menus (TO Grubtech)
+- `PUT /v1/menus/{id}` - Update existing menus (TO Grubtech)
+- `PATCH /v1/items/{id}/availability` - Update item availability (TO Grubtech)
+- POS systems PUSH menus TO Grubtech
 
 **2. Order Management**
 - `POST /v1/orders` - Create new orders (Ordering Platform → Grubtech)
@@ -298,18 +332,26 @@ Authorization: API-Key {your_api_key}
 - `PUT /v1/orders/{id}/status` - Update order status
 
 **3. Webhooks (Bidirectional)**
-- Order status updates
-- Order creation notifications (for POS integrations)
-- Order cancellations
-- Menu updates (if Grubtech modifies data)
-- Item availability changes
-
-**4. Delivery Management**
+- **Menu Upload** (Grubtech → Ordering Platform)
+- **Menu Update** (Grubtech → Ordering Platform)
+- **Item Availability** (Grubtech → Ordering Platform)
+- **Order Creation** (Grubtech → POS)
+- **Order Status Updates** (Grubtech → Ordering Platform)
+- **Order Cancellations**
+
+**4. GrubCenter (Restaurant Management Portal)**
+- Restaurant operators manage menus at https://grubcenter.grubtech.io/
+- Create and update menus, items, modifiers
+- Manage locations and stations
+- View orders and reports
+- When menus are created/updated, Grubtech pushes to Order Platforms
+
+**5. Delivery Management**
 - Delivery job assignment
 - Delivery status tracking
 - Driver assignment notifications
 
-**5. Authentication & Security**
+**6. Authentication & Security**
 - API key-based authentication
 - Webhook signature validation
 - HTTPS requirement
@@ -318,17 +360,30 @@ Authorization: API-Key {your_api_key}
 ### What Grubtech DOES NOT Provide
 
 **1. NO "Get Menu" API ⚠️**
-- There is **NO** `GET /v1/menus` endpoint
-- Menu sync is **PUSH-only** (you upload to Grubtech)
-- Cache menus in your local database after uploading
-- Use webhooks to receive menu updates FROM Grubtech
+- There is **NO** `GET /v1/menus` endpoint for querying menus
+- Menus flow one-way only:
+  - **Order Platform:** Receives menus via webhooks (must cache)
+  - **POS:** Sends menus via POST/PUT APIs (Grubtech stores and distributes)
+- You CANNOT pull/fetch menus on demand
 
-**Correct Pattern:**
+**Correct Patterns:**
+
+**For Order Platforms:**
+```
+1. Register webhook endpoint in Developer Portal
+2. Receive menu from Grubtech webhook (when restaurant creates/updates in GrubCenter)
+3. Cache/store menu in your local database
+4. Display menu from your cache to customers
+5. Update cache when receiving menu update webhooks (within 30 seconds)
+6. DO NOT make menu changes on your side if restaurant manages menus via Grubtech
+```
+
+**For POS Systems:**
 ```
 1. Upload menu to Grubtech (POST /v1/menus)
-2. Cache menu in your local database
-3. Display menu from your cache to customers
-4. Listen to webhooks for menu updates from Grubtech
+2. Grubtech stores and distributes to Order Platforms
+3. Update menu when items/prices change (PUT /v1/menus/{id})
+4. Update availability in real-time (PATCH /v1/items/{id}/availability)
 ```
 
 **2. NO Notification Services ⚠️**
@@ -354,9 +409,21 @@ Authorization: API-Key {your_api_key}
 
 ### Order Platform Integration Architecture
 
-**Flow: Customer Order → Grubtech → Restaurant/POS**
+**Flow: Menu Management + Order Flow**
 
 ```
+MENU FLOW:
+Restaurant
+  ↓ (creates/updates menu in GrubCenter)
+Grubtech gOnline
+  ↓ (menu webhook)
+Ordering Platform (You)
+  ↓ (cache menu, update within 30 sec)
+Ordering Platform Database
+  ↓ (display to)
+Customer
+
+ORDER FLOW:
 Customer
   ↓ (places order)
 Ordering Platform (You)
@@ -373,25 +440,50 @@ Customer
 ```
 
 **Your Responsibilities:**
-- Accept orders from customers
-- Push orders to Grubtech (POST /v1/orders)
-- Implement webhook endpoint for status updates
-- Notify customers of status changes
-- Handle menu display from cached data
-- Upload menus to Grubtech (POST /v1/menus)
+- **Menu Management:**
+  - Register webhook endpoint to RECEIVE menus from Grubtech
+  - Cache/store received menus in your database
+  - Display menus from your cache to customers
+  - Update cache when receiving menu update webhooks (within 30 seconds)
+  - DO NOT modify menus if restaurant manages them in GrubCenter
+
+- **Order Management:**
+  - Accept orders from customers
+  - Push orders to Grubtech (POST /v1/orders)
+  - Implement webhook endpoint for status updates
+  - Notify customers of status changes
 
 **Grubtech Responsibilities:**
+- Push menus to Order Platforms when restaurants create/update in GrubCenter
 - Validate and accept orders
 - Route orders to restaurant POS
 - Notify you of status changes
-- Store menu data
 - Coordinate order lifecycle
 
 ### POS Integration Architecture
 
-**Flow: Grubtech → POS → Grubtech**
+**Flow: Menu Upload + Order Reception**
 
 ```
+MENU FLOW:
+POS System (You)
+  ↓ (POST /v1/menus)
+Grubtech gOnline
+  ↓ (stores and distributes)
+Ordering Platforms
+  ↓ (receive via webhooks)
+Customers
+
+ITEM AVAILABILITY:
+POS System (You)
+  ↓ (PATCH /v1/items/{id}/availability)
+Grubtech gOnline
+  ↓ (pushes to Order Platforms)
+Ordering Platforms
+  ↓ (update cache, hide/show items)
+Customers
+
+ORDER FLOW:
 Ordering Platform
   ↓ (creates order)
 Grubtech gOnline
@@ -405,18 +497,23 @@ Grubtech gOnline
 ```
 
 **Your Responsibilities:**
-- Implement webhook endpoint to receive orders
-- Validate webhook signatures
-- Display orders in kitchen/POS
-- Update order status as it progresses
-- Upload menus to Grubtech
-- Update item availability in real-time
+- **Menu Management:**
+  - Upload menus to Grubtech (POST /v1/menus)
+  - Update menus when items/prices change (PUT /v1/menus/{id})
+  - Update item availability in real-time (PATCH /v1/items/{id}/availability)
+
+- **Order Management:**
+  - Implement webhook endpoint to receive orders
+  - Validate webhook signatures
+  - Display orders in kitchen/POS
+  - Update order status as it progresses
 
 **Grubtech Responsibilities:**
+- Store menus and distribute to Order Platforms
 - Send orders to your webhook endpoint
 - Accept status updates
 - Notify ordering platforms of changes
-- Store and distribute menu data
+- Push menu/availability updates to Order Platforms
 
 ### Delivery Integration Architecture
 
@@ -465,16 +562,26 @@ Grubtech gOnline
 - API key stored securely
 
 ### Phase 2: Menu Synchronization
-**Tasks:**
+
+**For Order Platform Suite:**
+- Register webhook endpoint to receive menus
+- Test receiving menu webhook from Grubtech
+- Implement menu caching in local database
+- Implement menu update webhook handler
+- Test cache updates within 30 seconds
+- Verify menus display correctly to customers
+
+**For POS Suite:**
 - Upload test menu (POST /v1/menus)
 - Verify menu in Grubtech dashboard
 - Implement menu updates (PUT /v1/menus/{id})
-- Cache menus in local database
-- Test item availability updates
-- Implement menu webhook handler
+- Test item availability updates (PATCH /v1/items/{id}/availability)
+- Verify Order Platforms receive menu updates
 
 **Verification:**
-- Menus visible in Grubtech system
+- Menus flow correctly based on integration type
+- Order Platforms cache menus from webhooks
+- POS systems upload menus successfully
 - Availability updates reflect immediately
 - Local cache stays in sync with Grubtech
 
@@ -547,20 +654,35 @@ Grubtech gOnline
 
 ### "How do I display menus to customers?"
 
-**Correct Approach:**
-1. Upload menu to Grubtech (POST /v1/menus)
-2. Store menu in YOUR local database (cache)
-3. Display menu from YOUR cache to customers
-4. Listen to webhooks for menu updates from Grubtech
-5. Update your cache when changes occur
+**Answer depends on your integration type:**
+
+**For Order Platform Suite (Food Aggregators):**
+1. **Register webhook endpoint** in Developer Portal to RECEIVE menus
+2. **Receive menu** from Grubtech webhook (when restaurant creates/updates in GrubCenter)
+3. **Cache menu** in YOUR local database
+4. **Display menu** from YOUR cache to customers
+5. **Listen for updates** - Grubtech sends menu update webhooks
+6. **Update cache** when receiving menu changes (within 30 seconds including cache invalidations)
+7. **DO NOT** make menu changes on your side if restaurant manages menus via Grubtech
+
+**Why this way?**
+- Restaurants manage menus in GrubCenter (https://grubcenter.grubtech.io/)
+- Grubtech pushes menus to Order Platforms via webhooks
+- You must cache for fast customer experience
+- Updates must be applied within 30 seconds
+
+**For POS Suite:**
+1. **Upload menu** to Grubtech (POST /v1/menus)
+2. **Grubtech stores** and distributes to Order Platforms
+3. **Update menu** when items/prices change (PUT /v1/menus/{id})
+4. **Update availability** in real-time (PATCH /v1/items/{id}/availability)
 
-**Why?**
-- There is NO `GET /v1/menus` endpoint
-- Menu sync is push-based only
-- Caching ensures fast customer experience
-- Reduces API calls and latency
+**Important:**
+- There is NO `GET /v1/menus` endpoint for querying menus
+- Order Platforms RECEIVE menus (via webhooks)
+- POS systems SEND menus (via POST/PUT APIs)
 
-**Source:** Use `search_grubtech_docs query="menu upload sync"` for official documentation
+**Source:** Use `search_grubtech_docs query="menu webhook integration"` for official documentation
 
 ### "How do webhooks work in Grubtech?"
 
@@ -844,10 +966,11 @@ Let me know which step reveals the issue, and I can help further!
 
 ---
 
-**Version:** 1.0.0
+**Version:** 1.1.0
 **Last Updated:** 2025-10-11
 **Support:** support@grubtech.com
 
 ## Changelog
 
+- **v1.1.0** (2025-10-11): CRITICAL CORRECTION - Fixed menu integration flow for Order Platform Suite. Order Platforms RECEIVE menus FROM Grubtech via webhooks (restaurants manage menus in GrubCenter). POS systems PUSH menus TO Grubtech via APIs. Added GrubCenter portal information (https://grubcenter.grubtech.io/). Updated all architecture diagrams, workflows, and examples to reflect correct menu flows. Added 30-second cache update requirement for Order Platforms.
 - **v1.0.0** (2025-10-11): Initial release. Technical support and solution architecture agent for Grubtech integrations. Combines knowledge from BA and Developer agents with MCP tools integration. Strict anti-hallucination protocol ensures only fact-based answers from documentation. Covers all three API suites: Ordering Platform, POS, and Delivery.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chanaka_nakandala/integration-personas",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Agent personas and slash commands for Claude Code to help with Grubtech API integration (Business Analyst, Developer, and Integration Assistant agents).",
   "type": "module",
   "files": [