JikoXpress Pro - Menu & Dish Management System Version: 1.0 Target Market: East African Restaurant Industry System Type: Kitchen Management System with Component-Based Inventory 1. System Overview JikoXpress Pro is a comprehensive restaurant kitchen management system designed specifically for the East African market. The system provides component-based inventory tracking, flexible menu scheduling, comprehensive waste management, and detailed profit analytics. Core Philosophy: Track everything at the component (dish) level, regardless of how items are sold - standalone, in combos, or custom builds. 2. Core Concepts 2.1 Dish (Component) The fundamental building block of the entire system. A dish is any individual food item that can be: Sold standalone Combined into menu schedules Tracked in inventory Used in custom builds Dish Properties Property Type Description id UUID Unique identifier name String Display name (e.g., "Ugali", "Maharage") prepCost BigDecimal Cost to prepare one portion sellingPrice BigDecimal Standalone selling price currentInventory Integer Available portions canSellStandalone Boolean Whether item can be sold individually imageUrl String Required dish photo thumbnailUrl String Auto-generated thumbnail active Boolean Whether dish is available Dish Examples Dish: Ugali - prepCost: 100 TSH - sellingPrice: 300 TSH - canSellStandalone: true Dish: Maharage (Beans) - prepCost: 200 TSH - sellingPrice: 400 TSH - canSellStandalone: true Dish: Chai (Tea) - prepCost: 20 TSH - sellingPrice: 100 TSH - canSellStandalone: true Important: Dishes do NOT have time-based visibility. Time visibility is handled at the Menu Schedule level only. 2.2 Menu Schedule Pre-defined combinations of dishes with time-based visibility and promotional pricing. Menu Schedule Properties Property Type Description id UUID Unique identifier name String Display name (e.g., "Lunch Special") components List Dishes included in this menu componentCost BigDecimal Auto-calculated from components sellingPrice BigDecimal Manually set (can be promotional) category Enum MAIN_FOOD, DRINKS, SNACKS, DESSERTS session Enum BREAKFAST, LUNCH, DINNER, ALL_DAY scheduleType Enum ONE_TIME, DAILY, WEEKLY, PERMANENT menuType Enum COMBO, INDIVIDUAL_ITEM visibleFrom LocalTime Start time for visibility visibleUntil LocalTime End time for visibility activeDays Set For recurring schedules validFrom LocalDate Start date validity validUntil LocalDate End date validity active Boolean Master on/off switch heroImageUrl String Optional custom combo image Key Concepts 1. Category vs Session: Category (Product Type): Session (Time Slot): - MAIN_FOOD - BREAKFAST (6am-10am) - DRINKS - LUNCH (12pm-3pm) - SNACKS - DINNER (6pm-9pm) - DESSERTS - ALL_DAY 2. Schedule Types: ONE_TIME: Special event menu (e.g., "New Year Special") DAILY: Repeats every day within time window WEEKLY: Repeats on specific days (e.g., Mon-Fri only) PERMANENT: Always available (within time window) 3. Menu Types: COMBO: Multiple components (e.g., Ugali + Maharage) INDIVIDUAL_ITEM: Single component as menu item (e.g., standalone Chai) Menu Schedule Examples Combo Menu: Name: "Ugali + Maharage Special" Components: [Ugali, Maharage] Category: MAIN_FOOD Session: LUNCH Schedule Type: DAILY Menu Type: COMBO Visible: 12:00 - 15:00 Component Cost: 300 TSH (100 + 200) Selling Price: 600 TSH Profit Margin: 300 TSH (50%) Individual Item Menu: Name: "Chai" Components: [Chai] Category: DRINKS Session: BREAKFAST Schedule Type: DAILY Menu Type: INDIVIDUAL_ITEM Visible: 06:00 - 10:00 Component Cost: 20 TSH Selling Price: 100 TSH Profit Margin: 80 TSH 2.3 Selling Price Strategy Critical Design Decision: Selling prices exist at BOTH levels. Where Prices Are Set Level Purpose Example Dish Level Standalone/custom build sales Ugali = 300 TSH Menu Schedule Level Combo/promotional pricing "Ugali + Maharage" = 600 TSH Price Usage Rules Flow 1: Customer orders Menu Schedule → Use MENU price (600 TSH) → Allocate revenue proportionally to components Flow 2: Customer orders standalone dish → Use DISH price (300 TSH) → Full revenue to that dish Flow 3: Custom build → Sum of DISH prices (300 + 400 = 700 TSH) → Each component gets full price Same Components, Different Prices Scenario Price Source Amount ───────────────────────────────────────────────────────── "Ugali + Maharage Special" Menu 600 TSH Ugali standalone Dish 300 TSH Maharage standalone Dish 400 TSH Custom: Ugali + Maharage Sum of Dishes 700 TSH 2.4 Dish Pairing (Smart Sides) Dish pairings power the Smart Sides popup in the counter app. They define which sides appear when a main dish is selected. Pairing Properties Property Type Description id UUID Unique identifier mainDish Dish The main dish (e.g., Ugali) sideDish Dish The suggested side (e.g., Maharage) combo MenuSchedule Linked combo if exists (nullable) source Enum COMBO, BEHAVIOR, MANUAL orderCount Integer Times ordered together savings BigDecimal Discount if combo exists displayOrder Integer Sort priority in popup active Boolean Whether to show in popup Pairing Sources Source Description Badge in UI COMBO Derived from existing MenuSchedules 💰 SAVE X BEHAVIOR Learned from customer order patterns 🔥 Popular MANUAL Admin-defined suggestions (none) How Pairings Are Generated Source 1: From Existing Combos System automatically scans all MenuSchedules and creates pairings. MenuSchedule: "Ugali Maharage" (Ugali + Maharage) → Creates pairing: Ugali → Maharage (source: COMBO, savings: 100) MenuSchedule: "Ugali Nyama" (Ugali + Nyama) → Creates pairing: Ugali → Nyama (source: COMBO, savings: 150) Source 2: From Customer Behavior System analyzes custom build orders to find frequent pairings. Analysis finds: - Ugali + Kachumbari ordered 47 times (no combo exists) → Creates pairing: Ugali → Kachumbari (source: BEHAVIOR, orderCount: 47) - Chapati + Maharage ordered 32 times (no combo exists) → Creates pairing: Chapati → Maharage (source: BEHAVIOR, orderCount: 32) Source 3: Manual Admin Entry Admin can manually add pairings for strategic suggestions. Admin adds: - Chips → Kachumbari (always suggest salad with chips) → Creates pairing: Chips → Kachumbari (source: MANUAL) Popup Display Priority When showing the Smart Sides popup, pairings are sorted: COMBO pairings first (sorted by savings, highest first) BEHAVIOR pairings second (sorted by orderCount, highest first) MANUAL pairings last (sorted by displayOrder) 2.5 Behavior Learning System The system continuously learns from customer orders to improve suggestions. What It Tracks For every custom build order, the system records: Which main dish was selected Which sides were paired with it Date and time of order Restaurant location (for multi-location) Learning Rules Rule Threshold Action Minimum orders 10+ times Consider for pairing Time window Last 30 days Recent behavior only Already exists Skip Don't duplicate pairings Combo created Convert Change source to COMBO Admin Insights The system surfaces learned pairings to admins with recommendations: Suggested New Combos 🔥 Ugali + Kachumbari Ordered together 47 times this month No combo exists Potential monthly revenue if combo created: +12,000 TSH [Create Combo] [Ignore] [Hide] Underperforming Combos ⚠️ Wali + Samaki Only 3 orders this month Combo exists but rarely used [Promote] [Deactivate] [Keep] 3. Order Flow & Sales Tracking 3.1 Order Entity Structure Order ├── id: UUID ├── orderNumber: String (auto-generated) ├── orderType: MENU_SCHEDULE | CUSTOM_BUILD | STANDALONE ├── subtotal: BigDecimal ├── discountType: PERCENTAGE | FIXED_AMOUNT | PROMO_CODE | MANAGER_OVERRIDE ├── discountValue: BigDecimal ├── discountAmount: BigDecimal ├── total: BigDecimal ├── paymentMethod: CASH | MOBILE_MONEY ├── status: PENDING | COMPLETED | CANCELLED ├── createdBy: Staff ├── createdAt: LocalDateTime └── items: List OrderItem ├── id: UUID ├── dish: Dish ├── menuSchedule: MenuSchedule (nullable) ├── quantity: Integer ├── sourceType: MENU_SCHEDULE | CUSTOM_BUILD | STANDALONE ├── priceType: ALLOCATED | FULL_PRICE ├── originalPrice: BigDecimal ├── allocatedRevenue: BigDecimal ├── discountAllocation: BigDecimal ├── netRevenue: BigDecimal ├── prepCost: BigDecimal └── profit: BigDecimal 3.2 Three Sales Flows Flow 1: Menu Schedule Order Customer orders a pre-defined combo. Customer: "I want the Lunch Special" Order Created: - orderType: MENU_SCHEDULE - Menu: "Ugali + Maharage Special" (600 TSH) OrderItems Created: 1. Ugali - sourceType: MENU_SCHEDULE - menuScheduleId: "lunch-special" - priceType: ALLOCATED - allocatedRevenue: 257.14 TSH (proportional) - prepCost: 100 TSH - profit: 157.14 TSH 2. Maharage - sourceType: MENU_SCHEDULE - menuScheduleId: "lunch-special" - priceType: ALLOCATED - allocatedRevenue: 342.86 TSH (proportional) - prepCost: 200 TSH - profit: 142.86 TSH Inventory Impact: - Ugali: -1 - Maharage: -1 Flow 2: Standalone Order Customer orders a single dish. Customer: "Just Chai please" Order Created: - orderType: STANDALONE OrderItem Created: 1. Chai - sourceType: STANDALONE - menuScheduleId: null - priceType: FULL_PRICE - allocatedRevenue: 100 TSH (full price) - prepCost: 20 TSH - profit: 80 TSH Inventory Impact: - Chai: -1 Flow 3: Custom Build Order Counter staff builds a custom combination. Staff picks: Ugali + Maharage + Nyama Order Created: - orderType: CUSTOM_BUILD - Total: 300 + 400 + 600 = 1,300 TSH OrderItems Created: 1. Ugali - sourceType: CUSTOM_BUILD - priceType: FULL_PRICE - allocatedRevenue: 300 TSH - prepCost: 100 TSH - profit: 200 TSH 2. Maharage - sourceType: CUSTOM_BUILD - priceType: FULL_PRICE - allocatedRevenue: 400 TSH - prepCost: 200 TSH - profit: 200 TSH 3. Nyama - sourceType: CUSTOM_BUILD - priceType: FULL_PRICE - allocatedRevenue: 600 TSH - prepCost: 300 TSH - profit: 300 TSH Inventory Impact: - Ugali: -1 - Maharage: -1 - Nyama: -1 3.3 Revenue Allocation (Proportional) When selling menu combos, revenue is allocated proportionally based on standalone prices. Allocation Formula Component Allocation = Menu Price × (Component Standalone Price / Total Standalone Prices) Allocation Example Menu: "Ugali + Maharage Special" Selling Price: 600 TSH Components: - Ugali standalone: 300 TSH - Maharage standalone: 400 TSH Total standalone: 700 TSH Allocation: - Ugali: 600 × (300/700) = 600 × 0.4286 = 257.14 TSH - Maharage: 600 × (400/700) = 600 × 0.5714 = 342.86 TSH Total: 600 TSH ✓ Why Proportional? Restaurant owners need to see profit/loss per item. Proportional allocation ensures: Each item gets same percentage discount as the combo offers Fair distribution based on relative value Accurate item-level profitability reporting 4. Discount System 4.1 Discount Structure Design Decision: Order-level discounts only (not item-level). Discount Types Type Description Example PERCENTAGE Percentage off total 10% off FIXED_AMOUNT Fixed amount off 200 TSH off PROMO_CODE Promotional code "LUNCH10" MANAGER_OVERRIDE Manual discount with reason Customer complaint STAFF_MEAL 100% discount for staff Employee meal ROUNDING Cash rounding adjustment Round to 50/100 4.2 Discount Application Discounts are distributed proportionally to all items. Example Order: - Ugali + Maharage Special: 600 TSH - Wali + Nyama: 800 TSH - Chai: 100 TSH Subtotal: 1,500 TSH Discount: 10% = 150 TSH Distribution (same % to each): - Ugali + Maharage: 600 - 60 = 540 TSH (10% off) - Wali + Nyama: 800 - 80 = 720 TSH (10% off) - Chai: 100 - 10 = 90 TSH (10% off) Total: 1,350 TSH ✓ 4.3 Counter App Discount Flow ┌─────────────────────────────────┐ │ Current Order │ ├─────────────────────────────────┤ │ Ugali + Maharage Special 600 │ │ Chai 100 │ │ │ │ Subtotal: 700 │ │ │ │ [💰 Apply Discount] │ │ [✅ Complete Order] │ └─────────────────────────────────┘ ↓ Tap Apply Discount ┌─────────────────────────────────┐ │ Apply Discount │ ├─────────────────────────────────┤ │ Type: │ │ ○ Percentage (%) │ │ ○ Fixed Amount (TSH) │ │ ○ Promo Code │ │ │ │ Value: [10] % │ │ │ │ Reason: [Customer complaint___] │ │ │ │ Preview: │ │ Subtotal: 700 │ │ Discount: -70 │ │ ═══════════════════════ │ │ Total: 630 ✓ │ │ │ │ [Cancel] [Apply] │ └─────────────────────────────────┘ 4.4 Cash Rounding (Tanzania Specific) Tanzania uses cash denominations (50/100 TSH coins). System handles rounding. Rounding Options Calculated Total: 315 TSH Options: 1. Round to nearest 50: 300 TSH (customer saves 15) 2. Round to nearest 100: 300 TSH (customer saves 15) 3. Staff adjustment: Apply -15 discount 4. Credit to wallet: 15 TSH for next order Mobile Money No rounding needed - exact amounts supported. 5. Inventory Management 5.1 Component-Level Tracking Core Principle: All inventory is tracked at the dish (component) level, never at menu level. How It Works Sale: "Ugali + Maharage Special" Inventory Update: - Ugali: -1 portion - Maharage: -1 portion NOT: - "Ugali + Maharage Special": -1 ← WRONG! No menu-level inventory 5.2 Stock Adjustment System Three adjustment types with live calculation preview. Action 1: Prep New Batch Adds inventory when kitchen prepares food. ┌─────────────────────────────────┐ │ Prep New Batch - Beans │ ├─────────────────────────────────┤ │ Quantity prepared: [50] │ │ │ │ ┌─────────────────────────────┐ │ │ │ Calculation Preview: │ │ │ ├─────────────────────────────┤ │ │ │ Current stock: 15 │ │ │ │ Adding: +50 │ │ │ │ ═══════════════════════ │ │ │ │ New stock: 65 ✓ │ │ │ └─────────────────────────────┘ │ │ │ │ Prep cost (optional): [2000] │ │ Prepared by: Chef John (auto) │ │ Time: 8:00 AM (auto) │ │ │ │ [Cancel] [Confirm Prep] │ └─────────────────────────────────┘ Records: Quantity prepared Prep cost (optional) Who prepared Timestamp Action 2: Dump/Waste Removes inventory with waste tracking. ┌─────────────────────────────────┐ │ Dump/Waste - Ugali │ ├─────────────────────────────────┤ │ Quantity to dump: [10] │ │ │ │ ┌─────────────────────────────┐ │ │ │ Calculation Preview: │ │ │ ├─────────────────────────────┤ │ │ │ Current stock: 65 │ │ │ │ Removing: -10 │ │ │ │ ═══════════════════════ │ │ │ │ New stock: 55 ✓ │ │ │ │ Waste value: 400 💸 │ │ │ └─────────────────────────────┘ │ │ │ │ Reason: │ │ ○ Spoiled/Expired │ │ ● Poor quality │ │ ○ Overcooked │ │ ○ Dropped/Accident │ │ ○ End of day dump │ │ ○ Other: [___________] │ │ │ │ Dumped by: Chef Mary (auto) │ │ Time: 2:30 PM (auto) │ │ │ │ [Cancel] [Confirm Dump] │ └─────────────────────────────────┘ Waste Reasons: Spoiled/Expired Poor quality Overcooked Dropped/Accident End of day dump Other (free text) Action 3: Manual Adjust General corrections for edge cases. ┌─────────────────────────────────┐ │ Manual Adjust - Rice │ ├─────────────────────────────────┤ │ Adjustment type: │ │ ● Add inventory │ │ ○ Remove inventory │ │ │ │ Quantity: [5] │ │ │ │ ┌─────────────────────────────┐ │ │ │ Calculation Preview: │ │ │ ├─────────────────────────────┤ │ │ │ Current stock: 55 │ │ │ │ Adding: +5 │ │ │ │ ═══════════════════════ │ │ │ │ New stock: 60 ✓ │ │ │ └─────────────────────────────┘ │ │ │ │ Reason: │ │ ● Recount correction │ │ ○ Found missing stock │ │ ○ System error │ │ ○ Transfer from storage │ │ ○ Other: [___________] │ │ │ │ [Cancel] [Confirm Adjustment] │ └─────────────────────────────────┘ Adjustment Reasons: Recount correction Found missing stock System error Transfer from storage Other (free text) 5.3 Error Prevention Cannot Remove More Than Available Quantity to dump: [100] ┌─────────────────────────────────┐ │ Calculation Preview: │ ├─────────────────────────────────┤ │ Current stock: 60 │ │ Removing: -100 │ │ ═══════════════════════ │ │ New stock: -40 ❌ │ │ │ │ ⚠️ Cannot remove more than │ │ available! │ │ Max: 60 portions │ └─────────────────────────────────┘ [Confirm] ← DISABLED Large Adjustment Warning If dumping > 15 portions OR value > 500 TSH: ┌─────────────────────────────────┐ │ ⚠️ Confirm Large Waste │ ├─────────────────────────────────┤ │ Dumping: 50 portions │ │ Value: 2,000 TSH │ │ Reason: End of day dump │ │ │ │ This is a significant loss. │ │ Please confirm. │ │ │ │ [Cancel] [Yes, Dump] │ └─────────────────────────────────┘ 5.4 Permission Recommendations Action Kitchen Staff Manager Prep New Batch ✓ ✓ Dump/Waste ✓ ✓ Manual Adjust ✗ ✓ 6. Counter App Interface 6.1 Smart Sides Flow (Core UX) The counter app uses a unified, intelligent flow that eliminates the need for staff to choose between "combos" or "custom builds". Staff simply taps what the customer orders, and the system handles combo detection automatically. Design Philosophy Old Approach New Smart Sides Approach Staff chooses: Combo OR Custom OR Standalone One natural flow for everything Must memorize which combos exist System suggests and auto-applies Three different paths to learn "Tap main, pick sides, done" Easy to pick wrong option Cannot go wrong The Flow Step 1: Staff sees main dishes only No combo clutter. Just the base items organized by category. ┌─────────────────────────────────────────────────┐ │ JikoXpress Counter │ ├─────────────────────────────────────────────────┤ │ │ │ MAIN DISHES │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐│ │ │ Ugali │ │ Wali │ │ Chapati │ │ Chips ││ │ │ 300 │ │ 250 │ │ 200 │ │ 400 ││ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘│ │ │ │ DRINKS │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ Chai │ │ Juice │ │ Soda │ │ │ │ 100 │ │ 200 │ │ 150 │ │ │ └─────────┘ └─────────┘ └─────────┘ │ │ │ └─────────────────────────────────────────────────┘ Step 2: Staff taps main dish → Smart Sides popup appears System shows all possible sides, with combo savings highlighted. ┌─────────────────────────────────────────────────┐ │ Add Sides to Ugali? [x] │ ├─────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────┐ │ │ │ Maharage +300 💰 SAVE 100 │ │ │ │ Combo available! │ │ │ └─────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────┐ │ │ │ Nyama Choma +500 💰 SAVE 150 │ │ │ │ Combo available! │ │ │ └─────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────┐ │ │ │ Kachumbari +150 🔥 Popular │ │ │ │ 47 orders │ │ │ └─────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────┐ │ │ │ Sukuma Wiki +200 │ │ │ └─────────────────────────────────────────────┘ │ │ │ │ [+ Custom Side] [Skip → No Sides] │ │ │ └─────────────────────────────────────────────────┘ Step 3: System auto-detects and applies combo pricing ┌─────────────────────────────────────────────────┐ │ Cart │ ├─────────────────────────────────────────────────┤ │ │ │ Ugali Maharage x1 600 │ │ ├─ Ugali │ │ └─ Maharage 💰 Saved 100! │ │ │ │ ───────────────────────────────────────────── │ │ Subtotal: 600 │ │ │ │ [+ Add More] [Checkout →] │ │ │ └─────────────────────────────────────────────────┘ 6.2 Smart Sides Popup Logic What Appears in the Popup The popup shows sides from three sources, in priority order: Priority Source Badge Description 1 Existing Combos 💰 SAVE X Sides that complete a predefined combo 2 Customer Behavior 🔥 Popular Frequently ordered together (learned) 3 Manual Pairings (none) Admin-defined suggestions Popup Display Rules Show combo sides first (sorted by savings amount) Show popular/learned sides second (sorted by order count) Show manual pairings last Maximum 6-8 sides visible (scroll for more) Always show "Custom Side" and "Skip" options 6.3 Cart Intelligence The system automatically determines the best pricing based on what's selected. Scenario 1: Side Completes a Combo Staff picks: Ugali → Maharage Cart shows: ┌─────────────────────────────────────────────────┐ │ Ugali Maharage x1 600 │ │ 💰 Saved 100! │ └─────────────────────────────────────────────────┘ Internally tracked as: MENU_SCHEDULE order Revenue allocation: Proportional to components Scenario 2: No Sides Selected (Skip) Staff picks: Ugali → Skip Cart shows: ┌─────────────────────────────────────────────────┐ │ Ugali x1 300 │ └─────────────────────────────────────────────────┘ Internally tracked as: STANDALONE order Revenue: Full price to Ugali Scenario 3: Sides Don't Match Any Combo Staff picks: Ugali → Kachumbari (no combo exists) Cart shows: ┌─────────────────────────────────────────────────┐ │ Ugali x1 300 │ │ Kachumbari x1 150 │ └─────────────────────────────────────────────────┘ Internally tracked as: CUSTOM_BUILD order Revenue: Full standalone prices Scenario 4: Multiple Mains Customer: "Ugali na Wali, zote na maharage" Staff flow: 1. Tap Ugali → Pick Maharage → Cart: "Ugali Maharage x1 - 600" 2. Tap Wali → Pick Maharage → Cart adds: "Wali Maharage x1 - 650" Cart shows: ┌─────────────────────────────────────────────────┐ │ Ugali Maharage x1 600 │ │ Wali Maharage x1 650 │ │ ───────────────────────────────────────────── │ │ Subtotal: 1,250 │ └─────────────────────────────────────────────────┘ Each main is a separate cart item with its own sides flow. Scenario 5: Drinks as Main Customer: "Chai mbili tu" Staff flow: 1. Tap Chai → Skip (or popup shows no relevant sides) 2. Adjust quantity to 2 Cart shows: ┌─────────────────────────────────────────────────┐ │ Chai x2 200 │ └─────────────────────────────────────────────────┘ Drinks are treated as main dishes. They can have their own sides popup (e.g., Chai + Mandazi combo) or be skipped. 6.4 Quantity Handling Quantity applies to the entire combo, not individual components. Customer: "Ugali maharage mbili" Cart shows: ┌─────────────────────────────────────────────────┐ │ Ugali Maharage x2 1,200 │ │ 💰 Saved 200! │ └─────────────────────────────────────────────────┘ This means: - 2x Ugali portions - 2x Maharage portions - Combo price × 2 6.5 Cart & Checkout ┌─────────────────────────────────────────────────┐ │ Current Order │ ├─────────────────────────────────────────────────┤ │ │ │ Ugali Maharage x1 600 │ │ 💰 Saved 100 │ │ │ │ Wali Nyama x1 800 │ │ 💰 Saved 150 │ │ │ │ Chai x2 200 │ │ │ │ ───────────────────────────────────────────── │ │ Subtotal: 1,600 │ │ Discount (10%): -160 │ │ ═════════════════════════════════════════════ │ │ Total: 1,440 │ │ │ │ Total Saved from Combos: 250 │ │ │ │ [💰 Apply Discount] │ │ │ │ Payment Method: │ │ [💵 Cash] [📱 Mobile Money] │ │ │ │ [✅ Complete Order] │ │ │ └─────────────────────────────────────────────────┘ 6.6 Staff Training Summary The entire training can be reduced to: "Tap the main dish customer wants. Pick sides from the popup if they want any. If they want it plain, tap Skip. System handles the rest." No need to memorize combos. No need to choose between different order types. Just tap what you hear. 7. Customer App Flow 7.1 Time-Based Menu Display Customer app shows only menus currently visible based on time. 8:00 AM Customer View: ┌─────────────────────────────────────────────────┐ │ 🌅 Breakfast Menu │ ├─────────────────────────────────────────────────┤ │ │ │ COMBO DEALS │ │ ┌─────────────────────────────────────────────┐ │ │ │ 🍳 Mandazi + Chai 200 TSH │ │ │ │ 💰 Save 20! │ │ │ ├─────────────────────────────────────────────┤ │ │ │ 🍚 Ugali + Maharage 350 TSH │ │ │ │ 💰 Save 50! │ │ │ └─────────────────────────────────────────────┘ │ │ │ │ INDIVIDUAL ITEMS │ │ ┌─────────────────────────────────────────────┐ │ │ │ Mandazi 120 TSH │ │ │ │ Chai 100 TSH │ │ │ │ Ugali 200 TSH │ │ │ └─────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────┘ 7.2 Standalone Item Solution Problem: Customer wants just Mandazi, but only "Mandazi + Chai" combo exists. Solution: Create both combo AND individual menu schedules. Breakfast Menus (6:00 - 10:00): 1. "Mandazi + Chai" (combo) = 200 TSH 2. "Mandazi" (individual) = 120 TSH 3. "Chai" (individual) = 100 TSH Customer can choose: - Combo (save 20 TSH) - Just Mandazi - Just Chai 8. Reports & Analytics 8.1 Daily Sales Report ═══════════════════════════════════════════════════════ DAILY SALES REPORT - January 15, 2025 ═══════════════════════════════════════════════════════ SUMMARY: ─────────────────────────────────────────────────────── Total Orders: 45 Gross Sales: 50,000 TSH Discounts Given: -3,500 TSH (7%) Net Sales: 46,500 TSH Total Food Cost: 18,600 TSH Gross Profit: 27,900 TSH Profit Margin: 60% DISCOUNT BREAKDOWN: ─────────────────────────────────────────────────────── Manager Override: 2,000 TSH Promo Codes: 1,000 TSH Staff Meals: 500 TSH PAYMENT METHODS: ─────────────────────────────────────────────────────── Cash: 30,000 TSH (64%) Mobile Money: 16,500 TSH (36%) 8.2 Item Sales Report ═══════════════════════════════════════════════════════ ITEM SALES REPORT - January 15, 2025 ═══════════════════════════════════════════════════════ Item Qty Revenue Cost Profit Margin ─────────────────────────────────────────────────────────────── Ugali 45 11,571 4,500 7,071 61.1% Maharage 52 13,943 10,400 3,543 25.4% Wali 35 8,750 3,500 5,250 60.0% Nyama 28 15,736 8,400 7,336 46.6% Chai 30 3,000 600 2,400 80.0% ─────────────────────────────────────────────────────────────── TOTAL 190 53,000 27,400 25,600 48.3% TOP PERFORMERS (by profit): 1. Nyama: 7,336 TSH (28 sold) 2. Ugali: 7,071 TSH (45 sold) ⭐ High volume 3. Wali: 5,250 TSH (35 sold) ATTENTION NEEDED: 1. Maharage: 25.4% margin ⚠️ - High volume but lowest margin - Consider: raise prices or reduce prep cost 8.3 Item Deep Dive Report ═══════════════════════════════════════════════════════ UGALI - DETAILED P&L REPORT ═══════════════════════════════════════════════════════ Quantity Sold: 45 portions REVENUE BREAKDOWN: ─────────────────────────────────────────────────────── From Menu "Ugali + Maharage Special": 25 orders × 257.14 allocated = 6,428.50 From Menu "Ugali + Nyama Special": 15 orders × 240.00 allocated = 3,600.00 From Standalone: 5 orders × 300.00 full price = 1,500.00 From Custom Builds: (various allocations) = 42.50 ─────────────────────────────────────────────────────── Total Revenue: 11,571.00 Total Cost: 4,500.00 (45 × 100) ═══════════════════════════════════════════════════════ Gross Profit: 7,071.00 Profit Margin: 61.1% Average Revenue per Portion: 257.13 Cost per Portion: 100.00 Average Profit per Portion: 157.13 8.4 Waste Report ═══════════════════════════════════════════════════════ WASTE REPORT - January 15, 2025 ═══════════════════════════════════════════════════════ BY COMPONENT: ─────────────────────────────────────────────────────── Beans: 5 portions (200 TSH cost) • Spoiled: 3 portions • Poor quality: 2 portions Ugali: 12 portions (1,200 TSH cost) • End of day: 12 portions Rice: 3 portions (150 TSH cost) • Dropped: 3 portions ─────────────────────────────────────────────────────── TOTAL WASTE: 20 portions TOTAL COST: 1,550 TSH % OF FOOD COST: 2.8% WASTE BY REASON: ─────────────────────────────────────────────────────── End of day dump: 12 portions (60%) Spoiled: 3 portions (15%) Poor quality: 2 portions (10%) Dropped: 3 portions (15%) 8.5 Prep Report ═══════════════════════════════════════════════════════ PREP REPORT - January 15, 2025 ═══════════════════════════════════════════════════════ TIME STAFF ITEM QTY COST ─────────────────────────────────────────────────────── 08:00 Chef John Beans 50 2,000 08:30 Chef John Ugali 30 1,500 09:00 Chef Mary Rice 40 1,600 12:00 Chef John Beans 25 1,000 14:30 Chef Mary Ugali 20 1,000 ─────────────────────────────────────────────────────── TOTAL PREP COST: 7,100 BY CHEF: Chef John: 105 portions 4,500 TSH Chef Mary: 60 portions 2,600 TSH 8.6 Menu Engineering Matrix ═══════════════════════════════════════════════════════ MENU ENGINEERING MATRIX ═══════════════════════════════════════════════════════ │ High Profit │ Low Profit ──────────────┼──────────────────────┼───────────────── High Volume │ ⭐ STARS │ 🐴 WORKHORSES │ Nyama, Ugali │ Maharage │ → Promote heavily │ → Fix pricing ──────────────┼──────────────────────┼───────────────── Low Volume │ 🔮 PUZZLES │ 🐕 DOGS │ Wali │ (none currently) │ → Test promotions │ → Consider removing ──────────────┴──────────────────────┴───────────────── RECOMMENDATIONS: ─────────────────────────────────────────────────────── ⭐ Nyama: Keep promoting - high margin, growing volume ⭐ Ugali: Maintain quality - consistent performer 🐴 Maharage: Increase price to 450 or reduce prep cost 🔮 Wali: Run "Wali Specials" to boost volume 8.7 Audit Trail ═══════════════════════════════════════════════════════ ADJUSTMENT AUDIT - January 15, 2025 ═══════════════════════════════════════════════════════ TIME STAFF ACTION ITEM QTY REASON ─────────────────────────────────────────────────────── 08:00 Chef John PREP Beans +50 Morning prep 08:30 Chef John PREP Ugali +30 Morning prep 14:30 Chef Mary DUMP Ugali -3 Poor quality 16:00 Chef Mary DUMP Beans -2 Spoiled 20:00 Manager ADJUST Beans -2 Recount 20:30 Chef John DUMP Ugali -12 End of day ─────────────────────────────────────────────────────── LARGE ADJUSTMENTS (>15 portions or >500 TSH): • 20:30 - Ugali dump: 12 portions (1,200 TSH) Approved by: Manager Reason: End of day - remaining portions 9. Image Management 9.1 Strategy Entity Image Requirement Dish REQUIRED - all dishes must have image Menu Schedule OPTIONAL - custom hero image Fallback Use component images if no menu image 9.2 Image Sizes Original: 1200 × 1200 (storage) Large: 800 × 800 (desktop detail view) Medium: 600 × 600 (mobile, listings) Thumbnail: 200 × 200 (cart, small displays) 9.3 Image Requirements Format: JPEG or PNG (WebP preferred) Max Size: 5MB Min Size: 400 × 400 Quality: 80-85% compression 10. Data Models Summary 10.1 Complete Entity Diagram ┌─────────────────┐ │ Dish │ ├─────────────────┤ │ id │ │ name │ │ prepCost │ │ sellingPrice │ │ currentInventory│ │ canSellStandalone│ │ imageUrl │ │ active │ └────────┬────────┘ │ │ components ▼ ┌─────────────────┐ │ MenuSchedule │ ├─────────────────┤ │ id │ │ name │ │ category │ │ session │ │ scheduleType │ │ menuType │ │ sellingPrice │ │ visibleFrom │ │ visibleUntil │ │ activeDays │ │ active │ └────────┬────────┘ │ │ combo (nullable) ▼ ┌─────────────────┐ │ DishPairing │◄─────────────────────────────────┐ ├─────────────────┤ │ │ id │ │ │ mainDish │──► Dish │ │ sideDish │──► Dish │ │ combo │──► MenuSchedule (nullable) │ │ source │ (COMBO, BEHAVIOR, MANUAL) │ │ orderCount │ │ │ savings │ │ │ displayOrder │ │ │ active │ │ └─────────────────┘ │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ OrderItem │◄───────│ Order │ │ ├─────────────────┤ ├─────────────────┤ │ │ id │ │ id │ │ │ dish │ │ orderNumber │ │ │ menuSchedule │ │ orderType │ │ │ quantity │ │ subtotal │ │ │ sourceType │ │ discountType │ │ │ priceType │ │ discountAmount │ │ │ allocatedRevenue│ │ total │ │ │ prepCost │ │ paymentMethod │ │ │ profit │ │ status │ │ └─────────────────┘ │ createdBy │ │ │ createdAt │ │ └─────────────────┘ │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ StockAdjustment │ │ PairingAnalytics│───────┘ ├─────────────────┤ ├─────────────────┤ │ id │ │ id │ │ dish │ │ mainDish │ │ adjustmentType │ │ sideDish │ │ quantity │ │ orderCount │ │ reason │ │ lastOrdered │ │ reasonCategory │ │ periodStart │ │ costImpact │ │ periodEnd │ │ adjustedBy │ └─────────────────┘ │ adjustedAt │ │ previousStock │ │ newStock │ └─────────────────┘ 10.2 Enums Menu & Scheduling Enum Values MenuCategory MAIN_FOOD, DRINKS, SNACKS, DESSERTS FoodSession BREAKFAST, LUNCH, DINNER, ALL_DAY ScheduleType ONE_TIME, DAILY, WEEKLY, PERMANENT MenuType COMBO, INDIVIDUAL_ITEM Orders & Sales Enum Values OrderType MENU_SCHEDULE, CUSTOM_BUILD, STANDALONE SourceType MENU_SCHEDULE, CUSTOM_BUILD, STANDALONE PriceType ALLOCATED, FULL_PRICE OrderStatus PENDING, COMPLETED, CANCELLED PaymentMethod CASH, MOBILE_MONEY Discounts Enum Values DiscountType PERCENTAGE, FIXED_AMOUNT, PROMO_CODE, MANAGER_OVERRIDE, STAFF_MEAL, ROUNDING Inventory & Adjustments Enum Values AdjustmentType PREP, DUMP, MANUAL_ADD, MANUAL_REMOVE WasteReason SPOILED_EXPIRED, POOR_QUALITY, OVERCOOKED, DROPPED_ACCIDENT, END_OF_DAY, OTHER AdjustmentReason RECOUNT_CORRECTION, FOUND_MISSING, SYSTEM_ERROR, TRANSFER_FROM_STORAGE, OTHER Dish Pairings Enum Values PairingSource COMBO, BEHAVIOR, MANUAL 11. Key System Benefits For Restaurant Owners Real-time inventory - always know what's available Item-level profitability - see profit per dish Waste tracking - understand where money is lost Staff accountability - track who does what Menu optimization - identify stars and dogs Behavior insights - see what customers actually want Combo suggestions - system recommends new combos based on data For Kitchen Staff Simple prep tracking - one tap to log Easy waste logging - categorized reasons Live inventory - no surprise stockouts Clear audit trail - protect from blame For Counter Staff One simple flow - tap main, pick sides, done No memorization - system suggests combos Auto pricing - combos detected automatically Flexible discounts - handle any situation Clear totals - live calculation preview Multiple payment - cash and mobile money For Customers Faster service - staff doesn't fumble with options Always get best price - combos auto-applied Consistent experience - same flow every time For System Component-level truth - single source for inventory Proportional allocation - fair revenue distribution Complete audit - every action logged Learning engine - improves suggestions over time Scalable - handles growth from 10 to 10,000 orders 12. Implementation Checklist Phase 1: Core Setup Dish entity with inventory Menu Schedule entity Category and Session enums Basic CRUD operations Phase 2: Smart Sides Dish Pairing entity Auto-generate pairings from combos Pairing display priority logic Smart Sides popup component Phase 3: Orders Order entity OrderItem with source tracking Cart intelligence (combo detection) Revenue allocation service Discount application Phase 4: Inventory Stock adjustment system Prep tracking Waste management Audit trail Phase 5: Counter App Main dishes display Smart Sides popup Cart with combo badges Checkout flow Discount UI Phase 6: Behavior Learning Order pattern tracking Pairing analysis service Admin insights dashboard Combo suggestions Phase 7: Reports Daily sales summary Item profitability Waste reports Prep reports Menu engineering Pairing performance Phase 8: Customer App Time-based menu display Cart functionality Payment integration Order history Document Version: 1.0 Last Updated: December 2024 Author: JikoXpress Development Team