RAG Entity Definitions

Entity definitions, key concepts, relationships, business logic state machines, and integration points for AI agent context.

Core Entities

Entity	Definition	Example
Tenant	Top-level organization (franchise, enterprise)	"Burger Chain Inc."
Location	Physical restaurant or virtual location	"Downtown SF Store #42"
User	Person with platform access	Staff member, manager, customer
Role	Permission set assigned to users	"Server", "Manager", "Owner"
Order	Customer food/drink transaction	Order #12345 with 3 items
Menu	Collection of items for sale	"Lunch Menu", "Happy Hour"
Table	Physical or virtual dining spot	"Table 7", "Takeout #3"
Ticket	Kitchen order display record	KDS ticket for Order #12345

Business Entities

Entity	Definition	Example
Shift	Scheduled work period	"9AM-5PM Server Shift"
Time Punch	Clock in/out record	"Clocked in at 8:55 AM"
Reservation	Future table booking	"Party of 4, 7PM, Smith"
Gift Card	Stored value payment method	"$50 Gift Card #GC123"
Loyalty	Customer rewards program	"Gold member, 500 points"
Campaign	Marketing promotion	"20% off first order"

Technical Entities

Entity	Definition	Example
Edge Server	OlympusEdge on-premise device	"edge-sf-downtown-001"
Sync Queue	Pending cloud sync items	"45 orders queued"
Policy	Business rule configuration	"Auto-gratuity 18% for 6+"
Feature Flag	Feature toggle	"voice_ordering_enabled"
Webhook	Event notification endpoint	"orders.created -> POS"

---

Business Logic Summary

Order State Machine

DRAFT → OPEN → SENT → PREPARING → READY → SERVED → CLOSED
                 ↓                           ↓
              MODIFIED                    PAID

Table States

AVAILABLE → SEATED → ORDERED → SERVED → CHECK_DROPPED → CLEARED
                                             ↓
                                           PAID

Payment States

PENDING → AUTHORIZED → CAPTURED → COMPLETED
              ↓             ↓
           DECLINED     REFUNDED (partial/full)

Shift States

SCHEDULED → CLOCKED_IN → ON_BREAK → CLOCKED_OUT → APPROVED
                             ↓
                        OFF_BREAK

---

Integration Points

Payment Processors

Processor	Use Case	Integration
Stripe	Primary card processing	API + Terminal SDK
Square	Alternative processor	API
Adyen	Enterprise clients	API

Delivery Platforms

Platform	Integration Type
DoorDash	API + Webhook
Uber Eats	API + Webhook
Grubhub	API + Webhook

Accounting

System	Integration
QuickBooks	OAuth + API
Xero	OAuth + API
Sage	API

Communication

Channel	Provider
SMS	Twilio
Email	SendGrid
Voice	Twilio
Push	FCM/APNs

---

Error Handling

Common Error Codes

Code	Meaning	Resolution
400	Bad request	Check request body format
401	Unauthorized	Refresh token or re-login
403	Forbidden	User lacks permission
404	Not found	Resource doesn't exist
409	Conflict	Concurrent modification
422	Validation error	Check field requirements
429	Rate limited	Reduce request frequency
500	Server error	Retry with backoff

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Order items cannot be empty",
    "details": [
      {"field": "items", "message": "At least one item required"}
    ],
    "request_id": "req-abc123"
  }
}

---

AI Agent Specific Context

Maximus (Cockpit AI)

Maximus is the operations AI assistant in Cockpit. Capabilities:

• Monitor system health and alerts
• Answer operational questions
• Execute runbooks (with approval for risky actions)
• Provide real-time metrics and insights
• Manage incident response

Common Commands:

• "What's the current P1 status?"
• "Who is on-call for platform?"
• "Show me orders per minute for SF Downtown"
• "Why did auth-service latency spike?"
• "Execute memory runbook for order-service"

Minerva (Sales AI)

Minerva is the sales and marketing AI. Capabilities:

• Lead qualification and scoring
• Meeting scheduling
• Demo assistance
• ROI calculations
• Competitive analysis

Common Queries:

• "What features does competitor X have?"
• "Calculate ROI for 5-location restaurant"
• "Schedule demo with lead #1234"
• "What's our pricing for enterprise tier?"

Menu Assistant

AI assistant for restaurant staff. Capabilities:

• Answer menu questions
• Suggest items based on preferences
• Handle dietary restrictions
• Explain ingredients and allergens

Common Queries:

• "What's gluten-free on the menu?"
• "Describe the chef's special"
• "What pairs well with the ribeye?"
• "Is the pasta vegan-friendly?"

Customer Support Agent

AI assistant for customer support. Capabilities:

• Answer common questions
• Process simple requests
• Escalate complex issues
• Track order status

Common Queries:

• "Where is my order?"
• "How do I update my payment method?"
• "I need to cancel my reservation"
• "How do I earn loyalty points?"

---

Data Freshness

Data Type	Update Frequency	Cache TTL
Orders	Real-time	0 (no cache)
Menu items	On change	5 minutes
Inventory	Real-time	0 (no cache)
Schedules	On change	15 minutes
Analytics	5 minutes	5 minutes
Reports	Hourly	1 hour

---

Security Context

Data Classification

Classification	Examples	Handling
Public	Menu items, hours	No restrictions
Internal	Revenue, metrics	Employee access
Confidential	Customer PII	Encrypted, audit logged
Restricted	Payment data	PCI compliant, tokenized

Access Control

• RBAC - Role-based access control for all operations
• MFA - Required for admin and financial access
• Audit Logging - All data access is logged
• Encryption - Data encrypted at rest and in transit

---

Performance Benchmarks

Operation	Target Latency	P99
Order creation	Under 100ms	Under 200ms
Payment processing	Under 2s	Under 3s
Menu fetch	Under 50ms	Under 100ms
KDS update	Under 50ms	Under 100ms
Search	Under 200ms	Under 500ms
Report generation	Under 5s	Under 10s

---

Related Pages

• Querying - Query patterns and retrieval strategies
• Indexing - How documents are indexed
• Overview - RAG Knowledge Base overview