# JikoXpress DishMng

# 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

<table id="bkmrk-property-type-descri"><thead><tr><th>Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>`id`</td><td>UUID</td><td>Unique identifier</td></tr><tr><td>`name`</td><td>String</td><td>Display name (e.g., "Ugali", "Maharage")</td></tr><tr><td>`prepCost`</td><td>BigDecimal</td><td>Cost to prepare one portion</td></tr><tr><td>`sellingPrice`</td><td>BigDecimal</td><td>Standalone selling price</td></tr><tr><td>`currentInventory`</td><td>Integer</td><td>Available portions</td></tr><tr><td>`canSellStandalone`</td><td>Boolean</td><td>Whether item can be sold individually</td></tr><tr><td>`imageUrl`</td><td>String</td><td>Required dish photo</td></tr><tr><td>`thumbnailUrl`</td><td>String</td><td>Auto-generated thumbnail</td></tr><tr><td>`active`</td><td>Boolean</td><td>Whether dish is available</td></tr></tbody></table>

### 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

<table id="bkmrk-property-type-descri-1"><thead><tr><th>Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>`id`</td><td>UUID</td><td>Unique identifier</td></tr><tr><td>`name`</td><td>String</td><td>Display name (e.g., "Lunch Special")</td></tr><tr><td>`components`</td><td>List&lt;Dish&gt;</td><td>Dishes included in this menu</td></tr><tr><td>`componentCost`</td><td>BigDecimal</td><td>Auto-calculated from components</td></tr><tr><td>`sellingPrice`</td><td>BigDecimal</td><td>Manually set (can be promotional)</td></tr><tr><td>`category`</td><td>Enum</td><td>MAIN\_FOOD, DRINKS, SNACKS, DESSERTS</td></tr><tr><td>`session`</td><td>Enum</td><td>BREAKFAST, LUNCH, DINNER, ALL\_DAY</td></tr><tr><td>`scheduleType`</td><td>Enum</td><td>ONE\_TIME, DAILY, WEEKLY, PERMANENT</td></tr><tr><td>`menuType`</td><td>Enum</td><td>COMBO, INDIVIDUAL\_ITEM</td></tr><tr><td>`visibleFrom`</td><td>LocalTime</td><td>Start time for visibility</td></tr><tr><td>`visibleUntil`</td><td>LocalTime</td><td>End time for visibility</td></tr><tr><td>`activeDays`</td><td>Set&lt;DayOfWeek&gt;</td><td>For recurring schedules</td></tr><tr><td>`validFrom`</td><td>LocalDate</td><td>Start date validity</td></tr><tr><td>`validUntil`</td><td>LocalDate</td><td>End date validity</td></tr><tr><td>`active`</td><td>Boolean</td><td>Master on/off switch</td></tr><tr><td>`heroImageUrl`</td><td>String</td><td>Optional custom combo image</td></tr></tbody></table>

### 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

<table id="bkmrk-level-purpose-exampl"><thead><tr><th>Level</th><th>Purpose</th><th>Example</th></tr></thead><tbody><tr><td>**Dish Level**</td><td>Standalone/custom build sales</td><td>Ugali = 300 TSH</td></tr><tr><td>**Menu Schedule Level**</td><td>Combo/promotional pricing</td><td>"Ugali + Maharage" = 600 TSH</td></tr></tbody></table>

### 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

<table id="bkmrk-property-type-descri-2"><thead><tr><th>Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>`id`</td><td>UUID</td><td>Unique identifier</td></tr><tr><td>`mainDish`</td><td>Dish</td><td>The main dish (e.g., Ugali)</td></tr><tr><td>`sideDish`</td><td>Dish</td><td>The suggested side (e.g., Maharage)</td></tr><tr><td>`combo`</td><td>MenuSchedule</td><td>Linked combo if exists (nullable)</td></tr><tr><td>`source`</td><td>Enum</td><td>COMBO, BEHAVIOR, MANUAL</td></tr><tr><td>`orderCount`</td><td>Integer</td><td>Times ordered together</td></tr><tr><td>`savings`</td><td>BigDecimal</td><td>Discount if combo exists</td></tr><tr><td>`displayOrder`</td><td>Integer</td><td>Sort priority in popup</td></tr><tr><td>`active`</td><td>Boolean</td><td>Whether to show in popup</td></tr></tbody></table>

### Pairing Sources

<table id="bkmrk-source-description-b"><thead><tr><th>Source</th><th>Description</th><th>Badge in UI</th></tr></thead><tbody><tr><td>COMBO</td><td>Derived from existing MenuSchedules</td><td>💰 SAVE X</td></tr><tr><td>BEHAVIOR</td><td>Learned from customer order patterns</td><td>🔥 Popular</td></tr><tr><td>MANUAL</td><td>Admin-defined suggestions</td><td>(none)</td></tr></tbody></table>

### 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:

1. COMBO pairings first (sorted by savings, highest first)
2. BEHAVIOR pairings second (sorted by orderCount, highest first)
3. 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

<table id="bkmrk-rule-threshold-actio"><thead><tr><th>Rule</th><th>Threshold</th><th>Action</th></tr></thead><tbody><tr><td>Minimum orders</td><td>10+ times</td><td>Consider for pairing</td></tr><tr><td>Time window</td><td>Last 30 days</td><td>Recent behavior only</td></tr><tr><td>Already exists</td><td>Skip</td><td>Don't duplicate pairings</td></tr><tr><td>Combo created</td><td>Convert</td><td>Change source to COMBO</td></tr></tbody></table>

### 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 &amp; 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>

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

<table id="bkmrk-type-description-exa"><thead><tr><th>Type</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>`PERCENTAGE`</td><td>Percentage off total</td><td>10% off</td></tr><tr><td>`FIXED_AMOUNT`</td><td>Fixed amount off</td><td>200 TSH off</td></tr><tr><td>`PROMO_CODE`</td><td>Promotional code</td><td>"LUNCH10"</td></tr><tr><td>`MANAGER_OVERRIDE`</td><td>Manual discount with reason</td><td>Customer complaint</td></tr><tr><td>`STAFF_MEAL`</td><td>100% discount for staff</td><td>Employee meal</td></tr><tr><td>`ROUNDING`</td><td>Cash rounding adjustment</td><td>Round to 50/100</td></tr></tbody></table>

## 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

<table id="bkmrk-action-kitchen-staff"><thead><tr><th>Action</th><th>Kitchen Staff</th><th>Manager</th></tr></thead><tbody><tr><td>Prep New Batch</td><td>✓</td><td>✓</td></tr><tr><td>Dump/Waste</td><td>✓</td><td>✓</td></tr><tr><td>Manual Adjust</td><td>✗</td><td>✓</td></tr></tbody></table>

---

# 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

<table id="bkmrk-old-approach-new-sma"><thead><tr><th>Old Approach</th><th>New Smart Sides Approach</th></tr></thead><tbody><tr><td>Staff chooses: Combo OR Custom OR Standalone</td><td>One natural flow for everything</td></tr><tr><td>Must memorize which combos exist</td><td>System suggests and auto-applies</td></tr><tr><td>Three different paths to learn</td><td>"Tap main, pick sides, done"</td></tr><tr><td>Easy to pick wrong option</td><td>Cannot go wrong</td></tr></tbody></table>

### 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:

<table id="bkmrk-priority-source-badg"><thead><tr><th>Priority</th><th>Source</th><th>Badge</th><th>Description</th></tr></thead><tbody><tr><td>1</td><td>Existing Combos</td><td>💰 SAVE X</td><td>Sides that complete a predefined combo</td></tr><tr><td>2</td><td>Customer Behavior</td><td>🔥 Popular</td><td>Frequently ordered together (learned)</td></tr><tr><td>3</td><td>Manual Pairings</td><td>(none)</td><td>Admin-defined suggestions</td></tr></tbody></table>

### 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 &amp; 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 &amp; 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

<table id="bkmrk-entity-image-require"><thead><tr><th>Entity</th><th>Image Requirement</th></tr></thead><tbody><tr><td>Dish</td><td>**REQUIRED** - all dishes must have image</td></tr><tr><td>Menu Schedule</td><td>**OPTIONAL** - custom hero image</td></tr><tr><td>Fallback</td><td>Use component images if no menu image</td></tr></tbody></table>

## 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 &amp; Scheduling**

<table id="bkmrk-enum-values-menucate"><thead><tr><th>Enum</th><th>Values</th></tr></thead><tbody><tr><td>MenuCategory</td><td>MAIN\_FOOD, DRINKS, SNACKS, DESSERTS</td></tr><tr><td>FoodSession</td><td>BREAKFAST, LUNCH, DINNER, ALL\_DAY</td></tr><tr><td>ScheduleType</td><td>ONE\_TIME, DAILY, WEEKLY, PERMANENT</td></tr><tr><td>MenuType</td><td>COMBO, INDIVIDUAL\_ITEM</td></tr></tbody></table>

**Orders &amp; Sales**

<table id="bkmrk-enum-values-ordertyp"><thead><tr><th>Enum</th><th>Values</th></tr></thead><tbody><tr><td>OrderType</td><td>MENU\_SCHEDULE, CUSTOM\_BUILD, STANDALONE</td></tr><tr><td>SourceType</td><td>MENU\_SCHEDULE, CUSTOM\_BUILD, STANDALONE</td></tr><tr><td>PriceType</td><td>ALLOCATED, FULL\_PRICE</td></tr><tr><td>OrderStatus</td><td>PENDING, COMPLETED, CANCELLED</td></tr><tr><td>PaymentMethod</td><td>CASH, MOBILE\_MONEY</td></tr></tbody></table>

**Discounts**

<table id="bkmrk-enum-values-discount"><thead><tr><th>Enum</th><th>Values</th></tr></thead><tbody><tr><td>DiscountType</td><td>PERCENTAGE, FIXED\_AMOUNT, PROMO\_CODE, MANAGER\_OVERRIDE, STAFF\_MEAL, ROUNDING</td></tr></tbody></table>

**Inventory &amp; Adjustments**

<table id="bkmrk-enum-values-adjustme"><thead><tr><th>Enum</th><th>Values</th></tr></thead><tbody><tr><td>AdjustmentType</td><td>PREP, DUMP, MANUAL\_ADD, MANUAL\_REMOVE</td></tr><tr><td>WasteReason</td><td>SPOILED\_EXPIRED, POOR\_QUALITY, OVERCOOKED, DROPPED\_ACCIDENT, END\_OF\_DAY, OTHER</td></tr><tr><td>AdjustmentReason</td><td>RECOUNT\_CORRECTION, FOUND\_MISSING, SYSTEM\_ERROR, TRANSFER\_FROM\_STORAGE, OTHER</td></tr></tbody></table>

**Dish Pairings**

<table id="bkmrk-enum-values-pairings"><thead><tr><th>Enum</th><th>Values</th></tr></thead><tbody><tr><td>PairingSource</td><td>COMBO, BEHAVIOR, MANUAL</td></tr></tbody></table>

---

# 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

# JikoXpress Pro: Checkout & Order Management Architecture

## Document Information

<table id="bkmrk-property-value-versi"><thead><tr><th>Property</th><th>Value</th></tr></thead><tbody><tr><td>Version</td><td>2.1</td></tr><tr><td>Status</td><td>Draft</td></tr><tr><td>Created</td><td>December 2025</td></tr><tr><td>Updated</td><td>January 2026</td></tr><tr><td>Purpose</td><td>Development Guide &amp; Requirements Reference</td></tr></tbody></table>

---

## Executive Summary

### Vision

JikoXpress Pro is a unified restaurant management platform designed for the East African market, enabling food businesses of any size to accept orders, manage kitchen operations, and grow their business - all from a single system.

### What is JikoXpress Pro?

JikoXpress Pro is a complete checkout and order management system that handles:

- **Order Capture** - From 7 different sales channels (POS, Kiosk, Mobile App, WhatsApp, Table QR, Drive-Through, Direct Counter)
- **Payment Processing** - Mobile money (USSD), cash, card, digital wallets, and pay-later tabs
- **Kitchen Operations** - Station-based routing, KDS displays, ticket printing, and expeditor control
- **Delivery Management** - Multi-provider integration with real-time tracking
- **Business Intelligence** - Sales reports, customer insights, and operational metrics

### Who Is It For?

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                         JIKOXPRESS PRO SERVES                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  🏠 HOME CHEFS              → Mobile app, basic menu, mobile money         │
│     Mama Lishe cooking        No hardware needed, just a smartphone        │
│     from home                                                               │
│                                                                             │
│  🛒 FOOD STALLS             → POS tablet, printers, multiple staff         │
│     Busy street vendors       Handle high volume with speed                 │
│                                                                             │
│  🍽️ RESTAURANTS             → Full KDS, stations, tabs, table service      │
│     Dine-in establishments    Complete front & back of house               │
│                                                                             │
│  🚗 FAST FOOD               → Drive-through, kiosks, customer displays     │
│     Quick service outlets     Speed-optimized workflows                     │
│                                                                             │
│  🏢 CHAINS                  → Multi-location, central menu, analytics      │
│     Franchise operations      Enterprise-grade management                   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

```

### Core Architecture Principles

The architecture is built on five core principles:

<table id="bkmrk-principle-descriptio"><thead><tr><th>Principle</th><th>Description</th></tr></thead><tbody><tr><td>**Single Source of Truth**</td><td>All channels (POS, Kiosk, App, WhatsApp, etc.) create the same Order entity. Kitchen sees one unified queue regardless of where orders originate.</td></tr><tr><td>**Progressive Feature Unlocking**</td><td>Start free with basic features. Unlock POS, stations, KDS, drive-through, and more as your business grows. Same platform from day one to 100 locations.</td></tr><tr><td>**Zero-Config Defaults**</td><td>Works immediately after signup. Set your menu, start taking orders. No complex setup required. Customize only what you need.</td></tr><tr><td>**Device-Agnostic Operations**</td><td>Register any device (phone, tablet, dedicated terminal) as POS, Kiosk, or KDS. Configure each device's role and capabilities independently.</td></tr><tr><td>**Channel-Flexible Menu**</td><td>One menu, configurable per channel. Set different prices for delivery, hide items from kiosks, restrict items by fulfillment type.</td></tr></tbody></table>

### System Overview

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           JIKOXPRESS PRO PLATFORM                            │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  SALES CHANNELS                    KITCHEN                   FULFILLMENT   │
│  ──────────────                    ───────                   ───────────   │
│                                                                             │
│  ┌─────────┐                   ┌─────────────┐              ┌──────────┐   │
│  │   POS   │──┐                │             │              │ Table 7  │   │
│  └─────────┘  │                │  STATIONS   │         ┌───▶│ (Waiter) │   │
│  ┌─────────┐  │                │  ─────────  │         │    └──────────┘   │
│  │  KIOSK  │──┤                │  Hot Line   │         │    ┌──────────┐   │
│  └─────────┘  │                │  Cold Line  │         │    │ Counter  │   │
│  ┌─────────┐  │  ┌─────────┐   │  Bar        │  READY  ├───▶│ (Pickup) │   │
│  │TABLE QR │──┼─▶│  ORDER  │──▶│  Bakery     │────────▶│    └──────────┘   │
│  └─────────┘  │  └─────────┘   │             │         │    ┌──────────┐   │
│  ┌─────────┐  │                │  ┌───────┐  │         │    │ Lane 1   │   │
│  │   APP   │──┤                │  │  KDS  │  │         ├───▶│ (Window) │   │
│  └─────────┘  │                │  └───────┘  │         │    └──────────┘   │
│  ┌─────────┐  │                │             │         │    ┌──────────┐   │
│  │WHATSAPP │──┤                └─────────────┘         │    │ Address  │   │
│  └─────────┘  │                                        └───▶│(Delivery)│   │
│  ┌─────────┐  │                                             └──────────┘   │
│  │DRIVE-TH │──┘                                                            │
│  └─────────┘                                                               │
│                                                                             │
│  PAYMENTS                      DEVICES                     INTEGRATIONS    │
│  ────────                      ───────                     ────────────    │
│  • Mobile Money (USSD)         • POS Terminals             • Bolt Food     │
│  • Cash                        • Kiosks                    • Uber Direct   │
│  • Card                        • KDS Displays              • SafeBoda      │
│  • App Wallet                  • Waiter Tablets            • JikoXpress    │
│  • Kitchen Wallet              • Customer Displays           Dashers       │
│  • Tabs (Pay Later)            • Printers                                  │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

```

### Subscription Tiers

<table id="bkmrk-tier-target-user-key"><thead><tr><th>Tier</th><th>Target User</th><th>Key Features</th><th>Limits</th></tr></thead><tbody><tr><td>**STARTER**</td><td>Home chefs, vendors</td><td>Mobile app, basic menu, mobile money</td><td>20 items, 100 orders/mo</td></tr><tr><td>**GROWING**</td><td>Small restaurants</td><td>+ POS, Kiosk, printers, card payments</td><td>1,000 orders/mo, 3 staff</td></tr><tr><td>**PROFESSIONAL**</td><td>Full restaurants</td><td>+ KDS, stations, tabs, drive-through</td><td>Unlimited orders, 15 staff</td></tr><tr><td>**ENTERPRISE**</td><td>Chains, franchises</td><td>+ Multi-location, API, white-label</td><td>Unlimited everything</td></tr></tbody></table>

### Key Differentiators

1. **East Africa First** - Built for M-Pesa, Tigo Pesa, Airtel Money. Designed for local restaurant workflows and trust models.
2. **Grow Without Migration** - A home chef on STARTER uses the same platform as a 50-location chain on ENTERPRISE. Upgrade your plan, not your system.
3. **Offline-Capable** - POS works offline, queues orders, syncs when connected. Critical for areas with unreliable internet.
4. **Multi-Channel by Default** - Not an add-on. Every kitchen can receive orders from POS, app, WhatsApp, and kiosks simultaneously from day one.
5. **Kitchen-Centric Design** - Built around how real kitchens work. Stations, expeditor control, parallel preparation, and clear handoff points.

### Document Scope

This architecture document covers:

- **Part 1-2**: Platform tiers, subscription plans, and sales channels
- **Part 3-5**: Order lifecycle, tabs, checkout flows
- **Part 6**: Payment architecture
- **Part 7-10**: Kitchen operations, stations, printing, configuration presets
- **Part 11-12**: Device management, menu channel settings
- **Part 13**: Data models and entity relationships
- **Part 14-15**: Unified system architecture, delivery integration
- **Part 16-18**: Operational scenarios, requirements, APIs
- **Appendices**: Glossary, configuration checklists, decision log

---

## Part 1: Platform Tiers &amp; Progressive Unlocking

### 1.1 The Vision: One Platform, All Scales

JikoXpress Pro is designed to grow with the business. A home chef starts with the simplest possible setup and progressively unlocks features as their operation scales.

```
STARTER          GROWING           PROFESSIONAL      ENTERPRISE
(Home Chef)      (Small Shop)      (Restaurant)      (Chain)

    📱      →      📱💻      →        💻🖥️      →       🏢🌐

• Mobile app     • + POS access    • + KDS           • + Multi-location
• Basic menu     • + Kiosk         • + Stations      • + Central menu
• Order list     • + Table QR      • + Drive-through • + Analytics
• Accept/Ready   • + Basic stats   • + Staff roles   • + API access
• Mobile money   • + More payments • + Tabs          • + Integrations
                 • + Printer       • + Inventory     • + White-label

```

### 1.2 Subscription Plans

#### STARTER Plan

**Tagline:** "Perfect for home chefs &amp; small vendors"

**Price:** Free or minimal fee

**Features Included:**

- Basic menu (up to 20 items)
- Order management (receive, accept, prepare, complete)
- Mobile app only
- Mobile money payments (USSD)
- Operating hours scheduling
- Order history (30 days)
- Table QR (1 table/location)
- Basic push notifications

**Limits:**

- 20 menu items
- 100 orders/month
- 1 staff account (owner only)
- 1 location

**Ideal For:** Home kitchens, street food vendors, side hustle chefs, testing the platform

---

#### GROWING Plan

**Tagline:** "For busy kitchens ready to scale"

**Price:** Mid-tier monthly fee

**Features Included:**

- Everything in STARTER
- Unlimited menu items
- POS access (desktop/tablet)
- Kiosk channel
- Table QR (unlimited)
- WhatsApp bot ordering
- Receipt printer support
- Kitchen printer support
- Card payments
- Cash handling
- Basic sales reports
- Order history (1 year)

**Limits:**

- 1,000 orders/month
- 3 staff accounts
- 1 location

**Ideal For:** Small restaurants, busy food stalls, cafes, food trucks

---

#### PROFESSIONAL Plan

**Tagline:** "Full-featured restaurant management"

**Price:** Higher-tier monthly fee

**Features Included:**

- Everything in GROWING
- Kitchen stations
- KDS (Kitchen Display System)
- Drive-through support
- Tabs (pay-later for dine-in)
- Table management
- Up to 15 staff accounts
- Roles &amp; permissions
- Discount limits by role
- Advanced reports
- Customer insights
- Priority support

**Limits:**

- Unlimited orders
- 15 staff accounts
- 1 location

**Ideal For:** Full-service restaurants, fast food outlets, bars &amp; lounges, hotel restaurants

---

#### ENTERPRISE Plan

**Tagline:** "For chains &amp; franchises"

**Price:** Custom pricing

**Features Included:**

- Everything in PROFESSIONAL
- Multi-location support
- Central menu management
- Consolidated cross-location reports
- API access for integrations
- Inventory management
- White-label option
- Dedicated support
- Custom integrations
- SLA guarantees

**Limits:**

- Unlimited everything

**Ideal For:** Restaurant chains, franchises, hotel groups, cloud kitchens with multiple brands

---

### 1.3 Smart Onboarding &amp; Segmentation

When a new kitchen signs up, 4 simple questions determine the recommended plan:

**Question 1: Business Type**

- Home Kitchen / Catering → Score: 0
- Food Stall / Vendor → Score: 1
- Restaurant / Cafe → Score: 2
- Chain / Multiple Locations → Score: 3

**Question 2: Expected Orders Per Day**

- Just starting (1-10/day) → Score: 0
- Getting busy (10-50/day) → Score: 1
- High volume (50-200/day) → Score: 2
- Very high (200+/day) → Score: 3

**Question 3: Team Size**

- Just me → Score: 0
- 2-5 people → Score: 1
- 6-15 people → Score: 2
- 15+ people → Score: 3

**Question 4: Service Styles (multi-select)**

- Delivery only → Score: 0
- Pickup only → Score: 0
- Dine-in → Score: +1
- Drive-through → Score: +2

**Recommendation Logic:**

- Score 0-2: STARTER
- Score 3-5: GROWING
- Score 6-8: PROFESSIONAL
- Score 9+: ENTERPRISE

### 1.4 Feature Modules (Unlockable)

Each feature is a module that can be toggled on/off based on subscription:

```
Kitchen Feature Modules:

CORE (Always On - STARTER):
├── basic_menu
├── order_management
├── mobile_notifications
├── basic_payments (mobile money)
├── operating_hours
└── order_history

CHANNELS (GROWING+):
├── pos_access
├── kiosk_channel
├── table_qr
└── whatsapp_bot

PAYMENTS (GROWING+):
├── card_payments
├── kitchen_wallet
├── cash_handling
└── custom_payment_methods

HARDWARE (GROWING+):
├── receipt_printer
├── kitchen_printer
└── cash_drawer

KITCHEN OPS (PROFESSIONAL+):
├── stations
├── kds_display
├── expeditor_mode
└── drive_through

DINE-IN (PROFESSIONAL+):
├── tabs
├── table_management
└── reservations (future)

TEAM (PROFESSIONAL+):
├── staff_accounts
├── roles_permissions
├── discount_limits
└── shift_management

INSIGHTS (PROFESSIONAL+):
├── sales_reports
├── popular_items
├── peak_hours
└── customer_insights

SCALE (ENTERPRISE):
├── multi_location
├── central_menu
├── consolidated_reports
├── api_access
└── white_label

INVENTORY (ENTERPRISE):
├── ingredient_tracking
├── auto_deduction
├── low_stock_alerts
└── supplier_orders

```

### 1.5 Usage-Based Upgrade Triggers

The platform monitors usage and suggests upgrades:

**STARTER → GROWING Triggers:**

- Orders this month &gt; 80 (approaching 100 limit)
- Menu items &gt; 15 (approaching 20 limit)
- Customer requested card payment
- Multiple login attempts (wants staff accounts)

**GROWING → PROFESSIONAL Triggers:**

- Orders this month &gt; 800 (approaching 1,000 limit)
- Staff accounts maxed at 3
- Searched for: tabs, dine-in, stations, KDS
- Average prep time &gt; 15 minutes

**PROFESSIONAL → ENTERPRISE Triggers:**

- Asked about second location
- Searched for: multi-location, franchise, API
- Orders this month &gt; 5,000

---

## Part 2: Sales Channels

### 2.1 Channel Overview

JikoXpress Pro supports seven distinct sales channels, each with unique characteristics.

#### POS (Point of Sale)

The primary channel for counter staff and waiters.

**Characteristics:**

- Staff-operated, requires speed and efficiency
- Supports both immediate payment and pay-later (tab) scenarios
- Full access to all payment methods
- Primary channel for dine-in customers
- Can lookup existing customers or create new ones
- Generates QR codes for customer self-payment via app

**Availability:** GROWING plan and above

**Typical Flow:**

1. Staff enters items into cart
2. Identifies customer (optional)
3. Selects fulfillment type (dine-in with table number)
4. Chooses payment timing: Pay Now or Pay Later (Tab)
5. Processes payment or opens tab
6. Kitchen receives order based on configuration

---

#### Kiosk

Self-service terminals for customer-driven ordering.

**Characteristics:**

- Customer-operated, must be intuitive
- Session-based cart storage
- Limited payment options (QR, USSD, Cash, Card Swipe)
- Primarily for dine-in and pickup customers
- Anonymous or optional login
- Prints order stub for customer

**Availability:** GROWING plan and above

**Typical Flow:**

1. Customer browses menu on touchscreen
2. Adds items to cart with modifications
3. Proceeds to checkout
4. Selects payment method
5. Completes payment (or receives cash payment slip)
6. Receives printed stub with order number
7. Waits for number to be called

---

#### Table QR

Self-ordering from customer's own device by scanning QR code at table.

**Characteristics:**

- Customer scans QR code placed on their table
- Opens in App (if installed) or Web browser (no app needed)
- No login required - anonymous ordering
- Table number automatically identified from QR
- Payment: USSD, Cash (pay at counter), App Wallet (if logged in)
- Dine-in only

**Availability:** STARTER plan (1 table), GROWING+ (unlimited)

**QR Code Content:**

```
https://menu.jikoxpress.com/{kitchenSlug}?table=5
or
jikoxpress://menu/{kitchenId}?table=5 (deep link for app)

```

**Web vs App Experience:**

<table id="bkmrk-aspect-web-%28no-app%29-"><thead><tr><th>Aspect</th><th>Web (No App)</th><th>App</th></tr></thead><tbody><tr><td>Login</td><td>Not required</td><td>Optional</td></tr><tr><td>Cart</td><td>Browser session</td><td>Persistent</td></tr><tr><td>Payment</td><td>USSD, Cash</td><td>USSD, Cash, Wallet</td></tr><tr><td>Order History</td><td>Not available</td><td>Available</td></tr><tr><td>Push Notifications</td><td>Not available</td><td>Available</td></tr></tbody></table>

---

#### Mobile App

Full-featured mobile application for registered users.

**Characteristics:**

- Requires user account
- Server-side persistent cart
- Supports delivery, pickup, and dine-in
- Preferred payment: App Wallet, USSD
- Push notifications for order status
- Order history and reordering

**Availability:** All plans (customer-facing)

---

#### WhatsApp

Conversational ordering via chatbot integration.

**Characteristics:**

- Customer identified by phone number
- Chatbot-guided ordering process
- Cart maintained in conversation state
- Payment via USSD or payment link
- Supports delivery and pickup only

**Availability:** GROWING plan and above

---

#### Drive-Through

Vehicle-based ordering and pickup.

**Characteristics:**

- Designed for speed - time SLA is critical
- Lane-based queue management
- Speaker/mic or digital menu board ordering
- Payment and pickup at windows
- Vehicle tracking by order number

**Availability:** PROFESSIONAL plan and above

**Typical Flow:**

1. Customer enters lane
2. Places order at order point (speaker or screen)
3. Proceeds to payment window
4. Proceeds to pickup window
5. Receives order and exits

---

#### Direct Counter Service

Simplified model for small operations where counter is kitchen.

**Characteristics:**

- Same person takes order and prepares food
- No kitchen routing needed
- Immediate handoff to customer
- May only need receipt, no kitchen ticket

**Availability:** All plans (default for STARTER)

---

### 2.2 Channel Comparison Matrix

<table id="bkmrk-aspect-pos-kiosk-tab"><thead><tr><th>Aspect</th><th>POS</th><th>Kiosk</th><th>Table QR</th><th>App</th><th>WhatsApp</th><th>Drive-Through</th></tr></thead><tbody><tr><td>Operator</td><td>Staff</td><td>Customer</td><td>Customer</td><td>Customer</td><td>Customer</td><td>Staff/Screen</td></tr><tr><td>Cart Storage</td><td>Memory</td><td>Session</td><td>Session/App</td><td>Server</td><td>Conversation</td><td>Memory</td></tr><tr><td>Customer ID</td><td>Optional</td><td>Anonymous</td><td>Anonymous</td><td>Required</td><td>Phone</td><td>Optional</td></tr><tr><td>Pay Later (Tab)</td><td>Yes</td><td>No</td><td>No</td><td>No</td><td>No</td><td>No</td></tr><tr><td>Fulfillment</td><td>All</td><td>Dine-in, Pickup</td><td>Dine-in</td><td>All</td><td>Delivery, Pickup</td><td>Drive-Through</td></tr><tr><td>Speed Priority</td><td>Critical</td><td>High</td><td>Normal</td><td>Normal</td><td>Normal</td><td>**Critical**</td></tr><tr><td>Time SLA</td><td>Normal</td><td>Normal</td><td>Normal</td><td>Normal</td><td>Normal</td><td>**Critical**</td></tr><tr><td>Min Plan</td><td>GROWING</td><td>GROWING</td><td>STARTER</td><td>All</td><td>GROWING</td><td>PROFESSIONAL</td></tr></tbody></table>

### 2.3 POS Service Modes

POS devices can operate in different service modes depending on the restaurant setup:

```yaml
POS Service Modes:

COUNTER_SERVICE:
  description: "Staff behind counter, customer faces them"
  flow:
    - Customer approaches counter
    - Staff takes order on POS
    - Customer waits at counter or takes number
  used_for: Fast food, cafes, takeaway

TABLE_SERVICE:
  description: "Waiter goes to customer's table with tablet"
  flow:
    - Customer seated at table
    - Waiter approaches with tablet
    - Waiter takes order at table
    - Table number captured
    - Food delivered to table
  used_for: Restaurants, fine dining, casual dining

```

**Service Mode Selection in POS:**

```
┌─────────────────────────────────────────────────────────────┐
│  New Order                                                  │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Service Type:                                              │
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  COUNTER    │  │   TABLE     │  │   PICKUP    │         │
│  │             │  │   SERVICE   │  │             │         │
│  │  Customer   │  │   Waiter    │  │  Customer   │         │
│  │  at counter │  │   at table  │  │  collects   │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│                                                             │
│  ┌─────────────┐  ┌─────────────┐                          │
│  │  DELIVERY   │  │   DRIVE-    │                          │
│  │             │  │   THROUGH   │                          │
│  └─────────────┘  └─────────────┘                          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

```

---

## Part 3: Order &amp; Tab Architecture

### 3.1 Core Concept: Single Source of Truth

All channels ultimately create Orders. The Order is the central entity that:

- Tracks what was purchased
- Connects to payment records
- Drives kitchen operations
- Generates receipts and reports

**Key Principle:** Cart is an unpersisted Order draft. Checkout persists the Order and initiates payment.

### 3.2 Order Lifecycle

```
CREATED → PENDING_PAYMENT → CONFIRMED → PREPARING → READY → COMPLETED
                ↓
            CANCELLED

```

**State Definitions:**

<table id="bkmrk-status-description-k"><thead><tr><th>Status</th><th>Description</th><th>Kitchen Visible</th><th>Payment Status</th></tr></thead><tbody><tr><td>CREATED</td><td>Order recorded but not yet submitted</td><td>No</td><td>Not started</td></tr><tr><td>PENDING\_PAYMENT</td><td>Awaiting async payment confirmation</td><td>Depends on config</td><td>In progress</td></tr><tr><td>CONFIRMED</td><td>Payment complete or tab opened</td><td>Yes</td><td>Paid or Deferred</td></tr><tr><td>PREPARING</td><td>Kitchen actively working on order</td><td>Yes</td><td>N/A</td></tr><tr><td>READY</td><td>Order complete, waiting for pickup</td><td>Yes</td><td>N/A</td></tr><tr><td>COMPLETED</td><td>Customer received order</td><td>No</td><td>N/A</td></tr><tr><td>CANCELLED</td><td>Order cancelled before completion</td><td>No</td><td>Refunded if paid</td></tr></tbody></table>

### 3.3 Payment Status (Separate from Order Status)

Orders track payment independently:

<table id="bkmrk-payment-status-descr"><thead><tr><th>Payment Status</th><th>Description</th></tr></thead><tbody><tr><td>UNPAID</td><td>No payment received (tab scenario)</td></tr><tr><td>PENDING</td><td>Async payment initiated, awaiting confirmation</td></tr><tr><td>PARTIAL</td><td>Some payment received (future feature)</td></tr><tr><td>PAID</td><td>Full payment received</td></tr><tr><td>REFUNDED</td><td>Payment returned to customer</td></tr></tbody></table>

### 3.4 Tab System (Pay Later)

Tabs enable the "eat now, pay later" model common in dine-in scenarios.

**Availability:** PROFESSIONAL plan and above

**What is a Tab?**

- A container for one or more orders at a table
- Remains open until customer is ready to pay
- Aggregates totals across all orders
- Single payment closes the entire tab

**Tab Lifecycle:**

```
[No Tab] → OPEN → CLOSED
             ↑
    (orders can be added while OPEN)

```

**Tab Rules:**

- Customer can add more orders to open tab
- Each order goes to kitchen independently
- Tab shows running total of all orders
- Discounts can be applied at tab level before closing
- Single payment closes tab and marks all orders as PAID

**Why Multiple Orders per Tab:**

- Kitchen already received and is preparing original order
- New items create new kitchen tickets
- Each order has clean, independent lifecycle
- Simplifies kitchen display and ticket management

### 3.5 Fulfillment Types

<table id="bkmrk-type-description-que"><thead><tr><th>Type</th><th>Description</th><th>Queue Identifier</th><th>Handoff Point</th></tr></thead><tbody><tr><td>DINE\_IN</td><td>Customer eats at restaurant</td><td>Table Number</td><td>Table</td></tr><tr><td>PICKUP</td><td>Customer collects order</td><td>Order Number</td><td>Counter</td></tr><tr><td>DELIVERY</td><td>Order delivered to customer</td><td>Address</td><td>Door</td></tr><tr><td>DRIVE\_THROUGH</td><td>Vehicle-based pickup</td><td>Lane + Order #</td><td>Window</td></tr></tbody></table>

---

## Part 4: Drive-Through Architecture

### 4.1 Overview

Drive-through is modeled as both a **channel** and a **fulfillment type**, allowing it to integrate seamlessly with the existing order system while supporting its unique requirements.

### 4.2 Drive-Through Flow

```
LANE_ENTRY → ORDER_POINT → PAYMENT_WINDOW → PICKUP_WINDOW → EXIT
     ↓            ↓              ↓               ↓
  (detected)  (order created) (payment)    (order handed)

```

### 4.3 Configuration Options

```yaml
Drive-Through Settings:
  enabled: false (default)
  numberOfLanes: 1-4
  
  orderPointType:
    - SPEAKER_MIC        # Staff takes order via speaker
    - DIGITAL_MENU_BOARD # Customer self-orders on screen
    - BOTH               # Screen with staff backup
  
  windowConfiguration:
    - SINGLE_WINDOW      # Pay and pickup at same window
    - SEPARATE_WINDOWS   # Payment window, then pickup window
  
  vehicleTracking:
    - ORDER_NUMBER       # Customer given number, called at window
    - MANUAL             # Staff tracks position manually
    - TIMER_BASED        # System estimates based on avg times

```

### 4.4 Drive-Through Order Properties

```yaml
Order (when fulfillment = DRIVE_THROUGH):
  laneNumber: 1-4
  vehicleDescription: "Red Toyota" (optional)
  orderPointTimestamp: when order was taken
  paymentWindowTimestamp: when payment completed
  pickupWindowTimestamp: when order handed off

```

### 4.5 Kitchen Ticket for Drive-Through

```
================================
        ORDER #47
     Lane 2 | DRIVE-THROUGH
   12:34 PM | 03-Jan-2026
--------------------------------
>> HOT LINE <<

1x Burger
   - No onions
   - Extra cheese

2x Fries
   - Large

--------------------------------
⚡ DRIVE-THROUGH - SPEED PRIORITY
================================

```

### 4.6 Drive-Through Metrics

Due to the critical nature of speed in drive-through:

**Tracked Metrics:**

- Average time per vehicle
- Time at each station (order, payment, pickup)
- Orders per hour per lane
- Peak hour analysis

**Alerts:**

- Order taking &gt; 2 minutes
- Payment processing &gt; 1 minute
- Pickup wait &gt; 3 minutes
- Lane backup detected

---

## Part 5: Checkout Flow

### 5.1 Universal Checkout Principles

Regardless of channel, checkout always involves:

1. **Identify Items** - What is being ordered
2. **Identify Customer** - Who is ordering (optional for some channels)
3. **Identify Fulfillment** - How order will be fulfilled
4. **Calculate Totals** - Items + taxes + fees - discounts
5. **Select Payment** - How customer will pay
6. **Process Payment** - Execute payment or defer
7. **Create/Confirm Order** - Finalize and notify kitchen

### 5.2 Default Flow (Zero Configuration)

If a kitchen sets nothing, this is what happens:

```yaml
Default Configuration:
  fulfillmentTypes: [PICKUP]
  paymentTiming: ON_PAYMENT_COMPLETE
  orderRouting: DISPLAY_ONLY
  kitchenNotification: DISPLAY
  printOnConfirm: true
  customerStub: true
  tabsEnabled: false

```

**Default Experience:**

1. Kitchen signs up
2. Sets their menu
3. Immediately can take orders via mobile app
4. Customer pays → Kitchen sees order on screen → Prepares → Calls number → Customer picks up

No stations, no tabs, no printers required. Just works.

### 5.3 Channel-Specific Checkout Flows

#### POS Checkout (Pay Now)

```
1. Staff finalizes cart
2. System creates checkout session
3. Staff selects customer (optional) and fulfillment
4. System calculates totals
5. Staff selects payment method
6. System processes payment
7. Order created with status CONFIRMED
8. Kitchen notified
9. Receipt printed

```

#### POS Checkout (Pay Later / Tab)

```
1. Staff finalizes cart
2. Staff selects "Pay Later" and enters table number
3. System finds/creates Tab for table
4. Order created with status CONFIRMED, paymentStatus UNPAID
5. Order linked to Tab
6. Kitchen notified immediately
7. Tab remains open for additional orders

[Later, when customer ready to pay]
8. Staff retrieves Tab for table
9. Staff applies discounts if needed
10. Staff processes payment
11. Tab closed, all orders marked PAID
12. Receipt printed

```

#### Drive-Through Checkout

```
1. Customer arrives at order point (lane assigned)
2. Staff/screen takes order
3. Order created with fulfillment DRIVE_THROUGH
4. Customer proceeds to payment window
5. Payment processed
6. Order status → CONFIRMED, sent to kitchen
7. Customer proceeds to pickup window
8. Kitchen prepares (priority queue)
9. Order handed to customer
10. Order status → COMPLETED

```

#### Kiosk / Table QR Checkout

```
1. Customer finalizes cart
2. System creates checkout session
3. Customer selects fulfillment
4. Customer selects payment method:
   - USSD: Receives prompt, confirms
   - Cash: "Pay at counter" displayed
5. On payment confirmation:
   - Order confirmed
   - Kitchen notified
   - Stub printed (kiosk) or shown on screen (Table QR)

```

### 5.4 Checkout Session

A checkout session provides:

- Temporary holding state during checkout
- Protection against abandoned checkouts
- Support for async payment flows

**Session States:**

<table id="bkmrk-status-description-a"><thead><tr><th>Status</th><th>Description</th></tr></thead><tbody><tr><td>ACTIVE</td><td>Checkout in progress</td></tr><tr><td>COMPLETED</td><td>Payment successful, order created</td></tr><tr><td>EXPIRED</td><td>Session timed out (15 min default)</td></tr><tr><td>CANCELLED</td><td>User or system cancelled</td></tr></tbody></table>

---

## Part 6: Payment Architecture

### 6.1 Payment Method Categories

#### Immediate Settlement

<table id="bkmrk-method-description-c"><thead><tr><th>Method</th><th>Description</th><th>Channels</th></tr></thead><tbody><tr><td>Cash</td><td>Physical currency</td><td>POS, Kiosk</td></tr><tr><td>Card Swipe</td><td>Card terminal</td><td>POS, Kiosk</td></tr><tr><td>Kitchen Wallet</td><td>Kitchen-issued balance</td><td>POS</td></tr><tr><td>App Wallet</td><td>Platform wallet</td><td>POS (QR), App</td></tr></tbody></table>

#### Asynchronous Settlement

<table id="bkmrk-method-description-c-1"><thead><tr><th>Method</th><th>Description</th><th>Channels</th></tr></thead><tbody><tr><td>Mobile Money (USSD)</td><td>Customer confirms on phone</td><td>All</td></tr><tr><td>QR Scan (App Wallet)</td><td>POS displays QR</td><td>POS</td></tr><tr><td>Payment Link</td><td>Customer clicks link</td><td>WhatsApp</td></tr></tbody></table>

#### Deferred Settlement

<table id="bkmrk-method-description-c-2"><thead><tr><th>Method</th><th>Description</th><th>Channels</th></tr></thead><tbody><tr><td>Pay Later (Tab)</td><td>Opens tab, pay before leaving</td><td>POS only</td></tr></tbody></table>

### 6.2 Payment Method by Plan

<table id="bkmrk-method-starter-growi"><thead><tr><th>Method</th><th>STARTER</th><th>GROWING</th><th>PROFESSIONAL</th><th>ENTERPRISE</th></tr></thead><tbody><tr><td>Mobile Money (USSD)</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td></tr><tr><td>Cash</td><td>-</td><td>✓</td><td>✓</td><td>✓</td></tr><tr><td>Card</td><td>-</td><td>✓</td><td>✓</td><td>✓</td></tr><tr><td>Kitchen Wallet</td><td>-</td><td>✓</td><td>✓</td><td>✓</td></tr><tr><td>App Wallet</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td></tr><tr><td>Pay Later (Tab)</td><td>-</td><td>-</td><td>✓</td><td>✓</td></tr><tr><td>Custom Methods</td><td>-</td><td>-</td><td>✓</td><td>✓</td></tr></tbody></table>

### 6.3 Kitchen Wallet

A prepaid balance system for loyal customers.

**Characteristics:**

- Issued and managed by individual kitchen
- Not platform-wide (unlike App Wallet)
- Can be topped up via cash at counter
- Used for quick payment without cash handling

**Use Cases:**

- Regular customers with running credit
- Corporate accounts
- Staff meals
- VIP customers

### 6.4 Discount Handling

**Discount Types:**

- Percentage: Reduce total by X%
- Fixed Amount: Reduce total by fixed value

**Staff Discount Limits (PROFESSIONAL+):**

- Each staff role has maximum discount percentage
- Exceeding limit requires manager approval (PIN)
- All discounts recorded with who applied and approved

---

## Part 7: Kitchen Operations

### 7.1 Operation Models

#### Model A: Direct Counter Service (Default for STARTER)

```
Order Confirmed → Same person prepares → Immediate handoff

```

No kitchen routing, no printers, no complexity.

#### Model B: Paper Ticket Kitchen

```
Order Confirmed → Print ticket → Kitchen works from paper

```

Traditional, reliable, no technology in kitchen.

#### Model C: Kitchen Display System (KDS)

```
Order Confirmed → Appears on screen → Kitchen marks done

```

Real-time visibility, paperless, item-level tracking.

#### Model D: Hybrid

```
Order Confirmed → Screen AND paper

```

Best of both, redundancy if one fails.

#### Model E: Expeditor Controlled (Fine Dining)

```
Order Confirmed → Expeditor screen → Expeditor fires items

```

Pacing control for multi-course meals.

### 7.2 Kitchen Stations (PROFESSIONAL+)

Larger kitchens have multiple stations. Each menu item is pre-assigned to a station during menu setup, and the system automatically routes order items to the appropriate stations.

**Common Stations:**

- Hot Line: Grills, fryers, sauté
- Cold Line: Salads, desserts
- Bar: Beverages, cocktails
- Bakery: Bread, pastries
- Expeditor: Final assembly

#### 7.2.1 Station Creation

Stations are created in Kitchen Settings by the admin:

```
┌─────────────────────────────────────────────────────────────────────────────┐
│  Kitchen Settings - Stations                                    [+ Add Station]│
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ 🔥 Hot Line                                              [Edit] [x] │   │
│  │    Grills, fryers, sauté - hot food preparation                    │   │
│  │    Menu Items: 12 │ KDS: KDS-HotLine                               │   │
│  ├─────────────────────────────────────────────────────────────────────┤   │
│  │ 🥗 Cold Line                                             [Edit] [x] │   │
│  │    Salads, desserts, cold appetizers                               │   │
│  │    Menu Items: 8 │ KDS: KDS-ColdLine                               │   │
│  ├─────────────────────────────────────────────────────────────────────┤   │
│  │ 🍺 Bar                                                   [Edit] [x] │   │
│  │    Beverages, cocktails, drinks                                    │   │
│  │    Menu Items: 15 │ KDS: KDS-Bar                                   │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

```

#### 7.2.2 Station Data Model

```yaml
Station:
  id: uuid
  kitchenId: uuid
  
  # Basic info
  name: "Hot Line"
  description: "Grills, fryers, sauté - hot food preparation"
  icon: "🔥"
  color: "#FF5733"  # For KDS display
  
  # Configuration
  displayOrder: 1  # Sort order on KDS
  printerId: uuid (nullable)  # Dedicated printer for this station
  
  # Status
  isActive: true
  
  # Timestamps
  createdAt: datetime
  updatedAt: datetime

```

#### 7.2.3 Menu Item Station Assignment

Each menu item is assigned to a station during creation/editing:

```yaml
MenuItem:
  id: uuid
  name: "Burger"
  price: 12000
  category: "Main Course"
  stationId: uuid  # ← Pre-defined assignment to station

```

#### 7.2.4 Station Routing Flow

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                         STATION ROUTING FLOW                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  Order #47 comes in:                                                        │
│  - 1x Burger (Hot Line)                                                     │
│  - 1x Salad (Cold Line)                                                     │
│  - 2x Beer (Bar)                                                            │
│         │                                                                   │
│         ▼                                                                   │
│  System routes to stations:                                                 │
│                                                                             │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                     │
│  │ KDS-HotLine │    │KDS-ColdLine │    │   KDS-Bar   │                     │
│  ├─────────────┤    ├─────────────┤    ├─────────────┤                     │
│  │ #47         │    │ #47         │    │ #47         │                     │
│  │ 1x Burger   │    │ 1x Salad    │    │ 2x Beer     │                     │
│  └─────────────┘    └─────────────┘    └─────────────┘                     │
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ KDS-Expeditor (sees ALL)                                            │   │
│  ├─────────────────────────────────────────────────────────────────────┤   │
│  │ #47: 1x Burger (Hot) │ 1x Salad (Cold) │ 2x Beer (Bar)              │   │
│  │      [WAITING]       │    [WAITING]    │    [WAITING]               │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  Each station marks items done → All done → Order READY                    │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

```

#### 7.2.5 Station Presets

For quick setup, kitchens can choose from presets:

<table id="bkmrk-preset-stations-crea"><thead><tr><th>Preset</th><th>Stations Created</th></tr></thead><tbody><tr><td>Fast Food</td><td>Hot Line, Cold Line, Drinks</td></tr><tr><td>Full Restaurant</td><td>Hot Line, Cold Line, Bar, Bakery, Expeditor</td></tr><tr><td>Cafe / Coffee Shop</td><td>Barista, Kitchen, Display</td></tr><tr><td>Pizza Place</td><td>Pizza Station, Grill, Salads, Bar</td></tr><tr><td>No Stations</td><td>All orders on single screen</td></tr></tbody></table>

**Station Routing Example:**

```
Order #47:
├── Burger → Hot Line
├── Caesar Salad → Cold Line
├── Beer → Bar
└── Cheesecake → Cold Line

```

### 7.3 Kitchen Timing Configuration

**When does kitchen receive the order?**

<table id="bkmrk-setting-description-"><thead><tr><th>Setting</th><th>Description</th><th>Use Case</th></tr></thead><tbody><tr><td>ON\_ORDER\_CREATED</td><td>Before payment</td><td>Trusted dine-in</td></tr><tr><td>ON\_PAYMENT\_COMPLETE</td><td>After payment</td><td>Kiosk, delivery</td></tr><tr><td>MANUAL</td><td>Staff triggers</td><td>Special events</td></tr></tbody></table>

**Default by Channel:**

- POS Dine-in: ON\_ORDER\_CREATED
- POS Pickup: ON\_PAYMENT\_COMPLETE
- Kiosk: ON\_PAYMENT\_COMPLETE
- Table QR: ON\_PAYMENT\_COMPLETE
- App: ON\_PAYMENT\_COMPLETE
- WhatsApp: ON\_PAYMENT\_COMPLETE
- Drive-Through: ON\_PAYMENT\_COMPLETE

### 7.4 Configuration Summary

```yaml
Kitchen Operation Settings:
  orderRouting:
    - DIRECT_TO_STATIONS
    - EXPEDITOR_CONTROLLED
    - DISPLAY_ONLY
    - NONE (counter service - default)
  
  notificationMethod:
    - DISPLAY (KDS)
    - PRINTER
    - BOTH
    - NONE (counter service - default)
  
  timingByChannel:
    pos_dine_in: ON_ORDER_CREATED | ON_PAYMENT_COMPLETE
    pos_pickup: ON_PAYMENT_COMPLETE
    kiosk: ON_PAYMENT_COMPLETE
    table_qr: ON_PAYMENT_COMPLETE
    app: ON_PAYMENT_COMPLETE
    whatsapp: ON_PAYMENT_COMPLETE
    drive_through: ON_PAYMENT_COMPLETE
  
  kioskCashFlow:
    - KITCHEN_FIRST (prepare before cash confirmed)
    - PAYMENT_FIRST (wait for cash - default)

```

---

## Part 8: Printing Architecture

### 8.1 Print Types

<table id="bkmrk-print-type-when-wher"><thead><tr><th>Print Type</th><th>When</th><th>Where</th><th>Purpose</th></tr></thead><tbody><tr><td>Kitchen Ticket</td><td>Order to kitchen</td><td>Kitchen printer</td><td>What to prepare</td></tr><tr><td>Customer Receipt</td><td>Payment completed</td><td>POS printer</td><td>Proof of purchase</td></tr><tr><td>Bill/Check</td><td>Customer requests</td><td>POS printer</td><td>Amount due</td></tr><tr><td>Order Stub</td><td>Kiosk order</td><td>Kiosk printer</td><td>Order number</td></tr><tr><td>Void Notice</td><td>Item voided</td><td>Kitchen printer</td><td>Cancel notification</td></tr></tbody></table>

### 8.2 Kitchen Ticket Example

```
================================
        ORDER #47
     Table 5 | Dine-in
   12:34 PM | 03-Jan-2026
--------------------------------
>> HOT LINE <<

1x Burger
   - No onions
   - Extra cheese

2x Fish & Chips
   - One mild spice

--------------------------------
Server: John
================================

```

### 8.3 Customer Receipt Example

```
================================
       JIKOXPRESS KITCHEN
    123 Main Street, Dar
      Tel: +255 123 456

      TAX ID: 12345678
================================
Receipt #: R-20260103-0047
Date: 03-Jan-2026 13:45
Table: 5
Server: John
--------------------------------
ITEMS:
1x Burger              12,000
   Extra cheese         1,500
2x Fish & Chips        30,000
--------------------------------
Subtotal:              43,500
Discount (10%):        -4,350
VAT (18%):              7,047
--------------------------------
TOTAL:                 46,197
================================
PAYMENT:
Mobile Money           46,197
Ref: MP12345678
================================
      Thank you!
================================

```

### 8.4 Print Architecture

**Model: Client Pull (Recommended)**

```
1. Order confirmed
2. Backend creates PrintJob (status: PENDING)
3. POS app polls: GET /print-jobs?status=PENDING
4. POS app claims job
5. POS app prints locally
6. POS app marks complete

```

Works with local USB/Bluetooth printers, supports offline queuing.

---

## Part 9: Numbering Systems

### 9.1 Order Number

- **Purpose:** Kitchen identification, customer reference
- **Format:** Simple integer, resets daily
- **Example:** #47

### 9.2 Receipt Number

- **Purpose:** Accounting, tax compliance
- **Format:** Prefix-Date-Sequence
- **Example:** R-20260103-0047
- Never resets (continuous with date prefix)

### 9.3 Internal IDs

- All entities have UUID primary keys
- Used for database relationships and API references
- Display numbers are separate from internal IDs

---

## Part 10: Configuration Presets

### 10.1 Available Presets

#### Home Kitchen Preset (STARTER Default)

```yaml
orderRouting: NONE
kitchenNotification: NONE
sendToKitchen: immediate (same person)
customerStub: false
customerDisplay: false
tabsEnabled: false

```

#### Fast Food Preset

```yaml
orderRouting: DIRECT_TO_STATIONS
kitchenNotification: DISPLAY
sendToKitchen: ON_PAYMENT_COMPLETE
customerStub: true
customerDisplay: true
tabsEnabled: false

```

#### Casual Dining Preset

```yaml
orderRouting: DIRECT_TO_STATIONS
kitchenNotification: PRINTER
sendToKitchen: ON_PAYMENT_COMPLETE
customerStub: optional
customerDisplay: false
tabsEnabled: true

```

#### Fine Dining Preset

```yaml
orderRouting: EXPEDITOR_CONTROLLED
kitchenNotification: BOTH
sendToKitchen: ON_ORDER_CONFIRMED
customerStub: false
customerDisplay: false
tabsEnabled: true (default for dine-in)

```

#### Drive-Through Preset

```yaml
orderRouting: DIRECT_TO_STATIONS
kitchenNotification: DISPLAY
sendToKitchen: ON_PAYMENT_COMPLETE
customerStub: false
customerDisplay: true (shows order numbers)
tabsEnabled: false
driveThrough:
  enabled: true
  lanes: 1
  combinedWindows: true

```

#### Food Truck Preset

```yaml
orderRouting: DISPLAY_ONLY
kitchenNotification: DISPLAY
sendToKitchen: ON_PAYMENT_COMPLETE
customerStub: true
customerDisplay: single screen
tabsEnabled: false

```

---

## Part 11: Device Management

### 11.1 Device Types &amp; Roles

Each app type knows its responsibilities:

```yaml
Device Types:

# ══════════════════════════════════════════════════════════════════════════════
# ORDER ENTRY DEVICES
# ══════════════════════════════════════════════════════════════════════════════

POS:
  role: "Staff order entry & payment processing"
  capabilities:
    - Create orders
    - Process payments
    - Manage tabs
    - Apply discounts
    - Print receipts
    - View order history
  used_by: Cashiers, Waiters, Counter Staff

KIOSK:
  role: "Customer self-service ordering"
  capabilities:
    - Browse menu
    - Create orders
    - Process payments (limited methods)
    - Print stubs
  used_by: Customers (unattended)

WAITER_TABLET:
  role: "Mobile order entry at tables"
  capabilities:
    - Same as POS
    - Optimized for table service
    - Quick table selection
  used_by: Waiters, Servers

# ══════════════════════════════════════════════════════════════════════════════
# KITCHEN DEVICES
# ══════════════════════════════════════════════════════════════════════════════

KDS (Kitchen Display System):
  role: "Kitchen order display & management"
  capabilities:
    - View incoming orders
    - Filter by station (optional)
    - Update item status
    - Mark orders ready
    - Bump orders
  used_by: Kitchen Staff, Line Cooks, Expeditor

# ══════════════════════════════════════════════════════════════════════════════
# CUSTOMER-FACING DISPLAYS (View Only)
# ══════════════════════════════════════════════════════════════════════════════

CUSTOMER_FACING_SCREEN:
  role: "Show current order being entered at POS"
  capabilities:
    - Mirror POS cart in real-time
    - Show items as they're added
    - Show running total
    - Show payment confirmation
  location: Counter (facing customer)
  used_by: Customers (view only, paired with POS)

ORDER_STATUS_DISPLAY:
  role: "Show order progress to waiting customers"
  capabilities:
    - Display "Now Preparing" orders
    - Display "Ready for Pickup" orders
    - Call order numbers
    - Show estimated wait time
  location: Waiting area, Counter
  used_by: Customers (view only)

MENU_BOARD:
  role: "Digital menu display"
  capabilities:
    - Show menu items with prices
    - Show item availability (live)
    - Show daily specials
    - Show promotions
    - Auto-hide sold out items
  location: Entrance, Above counter, Drive-through order point
  used_by: Customers (view only)

DRIVE_THROUGH_DISPLAY:
  role: "Order confirmation at drive-through"
  capabilities:
    - Show current order being taken
    - Show order total
    - Confirm items to customer
  location: Drive-through order point
  used_by: Customers in vehicle (view only)

QUEUE_DISPLAY:
  role: "Show queue/ticket numbers"
  capabilities:
    - Display current serving number
    - Display numbers being prepared
    - Play sound/chime when number called
    - Show multiple counters if applicable
  location: Waiting area
  used_by: Customers (view only)

```

### 11.1.1 Display Device Examples

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                         CUSTOMER-FACING DISPLAYS                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  CUSTOMER FACING SCREEN (at POS)                                           │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                        Your Order                                   │   │
│  │  ───────────────────────────────────────────────────────────────── │   │
│  │  1x Burger                                          TSh 12,000     │   │
│  │  1x Fries (Large)                                   TSh  5,000     │   │
│  │  1x Coke                                            TSh  2,500     │   │
│  │  ───────────────────────────────────────────────────────────────── │   │
│  │                                          Total:     TSh 19,500     │   │
│  │                                                                     │   │
│  │              "Please confirm your order with the cashier"           │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  ORDER STATUS DISPLAY (waiting area)                                       │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                                                                     │   │
│  │   NOW READY          │         PREPARING                           │   │
│  │   ──────────         │         ─────────                           │   │
│  │                      │                                              │   │
│  │   🔔 #42             │         #43  #44  #45                       │   │
│  │   🔔 #39             │         #46  #47                            │   │
│  │                      │                                              │   │
│  │   "Please collect    │                                              │   │
│  │    at counter"       │                                              │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  MENU BOARD (entrance / above counter)                                     │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                        🍔 TODAY'S MENU                              │   │
│  │  ───────────────────────────────────────────────────────────────── │   │
│  │                                                                     │   │
│  │  BURGERS                    │  SIDES                               │   │
│  │  Classic Burger    12,000   │  Fries (Reg)       3,000             │   │
│  │  Cheese Burger     14,000   │  Fries (Large)     5,000             │   │
│  │  Double Burger     18,000   │  Onion Rings       4,500             │   │
│  │  ░░ Veggie Burger ░░ SOLD OUT                                      │   │
│  │                             │  DRINKS                               │   │
│  │  CHICKEN                    │  Coke / Fanta      2,500             │   │
│  │  Grilled Chicken   15,000   │  Water             1,000             │   │
│  │  Chicken Wings     13,000   │  Fresh Juice       4,000             │   │
│  │                                                                     │   │
│  │  ─────────────────────────────────────────────────────────────────  │   │
│  │  🌟 TODAY'S SPECIAL: Burger + Fries + Drink = TSh 17,000 🌟        │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  QUEUE DISPLAY (simple number calling)                                     │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                                                                     │   │
│  │                         NOW SERVING                                 │   │
│  │                                                                     │   │
│  │                           ┌─────┐                                   │   │
│  │                           │ 42  │                                   │   │
│  │                           └─────┘                                   │   │
│  │                                                                     │   │
│  │                    Counter 1: #42                                   │   │
│  │                    Counter 2: #38                                   │   │
│  │                                                                     │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

```

### 11.2 Device Registration Flow

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                        DEVICE REGISTRATION FLOW                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  STEP 1: App Install                                                        │
│  ┌─────────────┐                                                            │
│  │ 📱 Device   │  App knows its type: POS | KIOSK | KDS | MOBILE           │
│  └─────────────┘                                                            │
│         │                                                                   │
│         ▼                                                                   │
│  STEP 2: Login                                                              │
│  ┌─────────────────────────────────────────────────────────────┐           │
│  │  Enter your email:                                          │           │
│  │  [admin@restaurant.com                    ]                 │           │
│  │                                                             │           │
│  │                    [Send Code →]                            │           │
│  └─────────────────────────────────────────────────────────────┘           │
│         │                                                                   │
│         ▼                                                                   │
│  STEP 3: Verify Code (sent to email)                                       │
│  ┌─────────────────────────────────────────────────────────────┐           │
│  │  Enter verification code:                                   │           │
│  │  [  5  ] [  8  ] [  3  ] [  2  ] [  9  ] [  1  ]           │           │
│  └─────────────────────────────────────────────────────────────┘           │
│         │                                                                   │
│         ▼                                                                   │
│  STEP 4: Select Kitchen (if account has multiple)                          │
│  ┌─────────────────────────────────────────────────────────────┐           │
│  │  Select Kitchen:                                            │           │
│  │                                                             │           │
│  │  ┌─────────────────────────────────────────────────────┐   │           │
│  │  │ 🍔 Mama Lishe Downtown                              │   │           │
│  │  │    123 Main Street, Dar                             │   │           │
│  │  └─────────────────────────────────────────────────────┘   │           │
│  │                                                             │           │
│  │  ┌─────────────────────────────────────────────────────┐   │           │
│  │  │ 🍔 Mama Lishe Airport                               │   │           │
│  │  │    Terminal 2, JK Airport                           │   │           │
│  │  └─────────────────────────────────────────────────────┘   │           │
│  └─────────────────────────────────────────────────────────────┘           │
│         │                                                                   │
│         ▼                                                                   │
│  STEP 5: Device Registered & Configured                                    │
│  ┌─────────────────────────────────────────────────────────────┐           │
│  │  ✅ Device Registered!                                      │           │
│  │                                                             │           │
│  │  Kitchen: Mama Lishe Downtown                               │           │
│  │  Device Type: POS                                           │           │
│  │  Device Name: POS-Counter-1                                 │           │
│  └─────────────────────────────────────────────────────────────┘           │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

```

**Key Rules:**

- One device operates for ONE kitchen at a time
- Must logout to switch kitchens
- Device appears in dashboard after registration
- Heartbeat every 30s to show online status

### 11.3 Device Data Model

```yaml
Device:
  id: uuid
  
  # Device identification
  deviceType: 
    # Order Entry
    - POS
    - KIOSK
    - WAITER_TABLET
    # Kitchen
    - KDS
    # Customer-Facing Displays
    - CUSTOMER_FACING_SCREEN
    - ORDER_STATUS_DISPLAY
    - MENU_BOARD
    - DRIVE_THROUGH_DISPLAY
    - QUEUE_DISPLAY
  
  deviceId: string (hardware ID or generated UUID)
  deviceName: "POS-Counter-1" | "Kiosk-Entrance" | "KDS-HotLine" | "Menu-Entrance"
  
  # Assignment
  kitchenId: uuid (currently assigned kitchen)
  accountId: uuid (owner account)
  
  # For KDS - which station does it show?
  stationId: uuid (nullable - null means ALL stations)
  
  # For POS/KIOSK - which fulfillment types allowed?
  allowedFulfillmentTypes: [DINE_IN, PICKUP, DELIVERY, DRIVE_THROUGH]
  
  # For POS - which service modes allowed?
  allowedServiceModes: [COUNTER, TABLE_SERVICE]
  
  # For CUSTOMER_FACING_SCREEN - which POS is it paired with?
  pairedDeviceId: uuid (nullable)
  
  # For MENU_BOARD - display settings
  menuBoardSettings:
    showPrices: true
    showSoldOut: true
    showSpecials: true
    categories: [uuid] (which categories to display, null = all)
    rotationInterval: 30 (seconds between slides, if multiple)
  
  # For ORDER_STATUS_DISPLAY / QUEUE_DISPLAY
  displaySettings:
    showPreparing: true
    showReady: true
    playSoundOnReady: true
    maxOrdersShown: 10
  
  # Status
  status: ACTIVE | INACTIVE | OFFLINE
  lastSeenAt: datetime
  
  # Metadata
  registeredAt: datetime
  registeredBy: staffId
  appVersion: string
  osVersion: string

```

### 11.4 KDS Station Assignment

When setting up a KDS device, admin chooses what it displays:

```
┌─────────────────────────────────────────────────────────────┐
│  KDS Setup - "KDS-Kitchen-1"                                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  This display will show orders for:                         │
│                                                             │
│  ○ All Stations (shows everything)                          │
│                                                             │
│  ● Specific Station:                                        │
│    ┌─────────────────────────────────────────────────────┐ │
│    │ ☑ Hot Line                                          │ │
│    │ ☐ Cold Line                                         │ │
│    │ ☐ Bar                                               │ │
│    │ ☐ Bakery                                            │ │
│    └─────────────────────────────────────────────────────┘ │
│                                                             │
│  ○ Expeditor View (all items, controls firing)              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

```

### 11.5 POS Fulfillment Configuration

Each POS device can be restricted to specific fulfillment types:

```
┌─────────────────────────────────────────────────────────────┐
│  POS Setup - "POS-Counter-1"                                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  This POS can accept orders for:                            │
│                                                             │
│  ☑ Dine-In (tables)                                        │
│  ☑ Pickup (customer collects)                              │
│  ☐ Delivery (send to address)                              │
│  ☐ Drive-Through                                           │
│                                                             │
│  Service Modes:                                             │
│                                                             │
│  ☑ Counter Service (customer at counter)                   │
│  ☑ Table Service (waiter at table)                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

```

**Example Device Configurations:**

<table id="bkmrk-device-fulfillment-t"><thead><tr><th>Device</th><th>Fulfillment Types</th><th>Service Modes</th><th>Location</th></tr></thead><tbody><tr><td>POS-Counter-1</td><td>Dine-In, Pickup</td><td>Counter</td><td>Main counter</td></tr><tr><td>POS-Counter-2</td><td>Pickup only</td><td>Counter</td><td>Takeaway window</td></tr><tr><td>POS-DriveThru</td><td>Drive-Through only</td><td>Counter</td><td>DT Window</td></tr><tr><td>Tablet-Waiter-1</td><td>Dine-In only</td><td>Table Service</td><td>Floor</td></tr><tr><td>Kiosk-Entrance</td><td>Dine-In, Pickup</td><td>N/A</td><td>Entrance</td></tr></tbody></table>

### 11.6 Dashboard - Device Overview

Admin dashboard shows all registered devices:

```
┌─────────────────────────────────────────────────────────────────────────────┐
│  Devices - Mama Lishe Downtown                                    [+ Add]   │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ORDER ENTRY DEVICES                                                        │
│  ═══════════════════                                                        │
│                                                                             │
│  POS (3)                                                                   │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ 🟢 POS-Counter-1      │ Dine-In, Pickup    │ Counter      │ [Edit] │   │
│  │ 🟢 POS-Counter-2      │ Pickup             │ Counter      │ [Edit] │   │
│  │ 🟢 POS-DriveThru      │ Drive-Through      │ Counter      │ [Edit] │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  WAITER TABLETS (2)                                                        │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ 🟢 Tablet-Waiter-1    │ Dine-In            │ Table Service│ [Edit] │   │
│  │ 🟡 Tablet-Waiter-2    │ Dine-In            │ Table Service│ [Edit] │   │
│  │    (offline 15 min)                                                 │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  KIOSKS (2)                                                                │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ 🟢 Kiosk-Entrance-1   │ Dine-In, Pickup    │ -            │ [Edit] │   │
│  │ 🟢 Kiosk-Entrance-2   │ Dine-In, Pickup    │ -            │ [Edit] │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  KITCHEN DEVICES                                                           │
│  ═══════════════                                                            │
│                                                                             │
│  KDS DISPLAYS (4)                                                          │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ 🟢 KDS-HotLine        │ Station: Hot Line  │              │ [Edit] │   │
│  │ 🟢 KDS-ColdLine       │ Station: Cold Line │              │ [Edit] │   │
│  │ 🟢 KDS-Bar            │ Station: Bar       │              │ [Edit] │   │
│  │ 🟢 KDS-Expeditor      │ All Stations       │              │ [Edit] │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  CUSTOMER-FACING DISPLAYS                                                  │
│  ════════════════════════                                                   │
│                                                                             │
│  CUSTOMER FACING SCREENS (2)                                               │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ 🟢 Screen-Counter-1   │ Paired: POS-Counter-1             │ [Edit] │   │
│  │ 🟢 Screen-Counter-2   │ Paired: POS-Counter-2             │ [Edit] │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  ORDER STATUS DISPLAYS (1)                                                 │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ 🟢 Status-WaitingArea │ Preparing + Ready  │ Sound: On    │ [Edit] │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  MENU BOARDS (2)                                                           │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ 🟢 Menu-Entrance      │ All Categories     │ Live         │ [Edit] │   │
│  │ 🟢 Menu-DriveThru     │ DT Menu Only       │ Live         │ [Edit] │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  QUEUE DISPLAYS (1)                                                        │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ 🟢 Queue-Counter      │ Now Serving        │ Sound: On    │ [Edit] │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  DRIVE-THROUGH DISPLAYS (1)                                                │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ 🟢 DT-OrderConfirm    │ Order Confirmation │ Lane 1       │ [Edit] │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  ═══════════════════════════════════════════════════════════════════════   │
│  Summary: 18 devices │ 17 online │ 1 offline                               │
└─────────────────────────────────────────────────────────────────────────────┘

```

---

## Part 12: Menu Channel Settings

### 12.1 Channel-Specific Visibility &amp; Pricing

Each menu item can have different visibility and pricing per channel:

```yaml
MenuItem:
  id: uuid
  name: "Burger"
  basePrice: 12000
  stationId: uuid  # Hot Line
  
  # Channel settings
  channelSettings:
    POS:
      visible: true
      price: 12000  # Same as base
    KIOSK:
      visible: true
      price: 12000
    APP:
      visible: true
      price: 13000  # +1000 for delivery convenience
    WHATSAPP:
      visible: true
      price: 13000
    TABLE_QR:
      visible: true
      price: 12000
    DRIVE_THROUGH:
      visible: true
      price: 12000
  
  # Fulfillment restrictions
  fulfillmentSettings:
    DINE_IN: available
    PICKUP: available
    DELIVERY: available
    DRIVE_THROUGH: unavailable  # e.g., soup not good for DT

```

### 12.2 Menu Item Setup UI

```
┌─────────────────────────────────────────────────────────────┐
│  Edit Menu Item - Burger                                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Name: [Burger                    ]                         │
│  Base Price: [12,000              ]                         │
│  Station: [Hot Line           ▼]                            │
│                                                             │
│  ─────────────────────────────────────────────────────────  │
│  CHANNEL SETTINGS                                           │
│  ─────────────────────────────────────────────────────────  │
│                                                             │
│  │ Channel      │ Visible │ Price    │                     │
│  │──────────────│─────────│──────────│                     │
│  │ POS          │   ☑     │ 12,000   │ (base)             │
│  │ Kiosk        │   ☑     │ 12,000   │                     │
│  │ Table QR     │   ☑     │ 12,000   │                     │
│  │ App          │   ☑     │ 13,000   │ (+1,000)           │
│  │ WhatsApp     │   ☑     │ 13,000   │ (+1,000)           │
│  │ Drive-Thru   │   ☑     │ 12,000   │                     │
│                                                             │
│  ─────────────────────────────────────────────────────────  │
│  FULFILLMENT AVAILABILITY                                   │
│  ─────────────────────────────────────────────────────────  │
│                                                             │
│  ☑ Dine-In                                                 │
│  ☑ Pickup                                                  │
│  ☑ Delivery                                                │
│  ☐ Drive-Through (not suitable)                            │
│                                                             │
└─────────────────────────────────────────────────────────────┘

```

### 12.3 Use Cases

<table id="bkmrk-scenario-configurati"><thead><tr><th>Scenario</th><th>Configuration</th></tr></thead><tbody><tr><td>Alcohol only on POS</td><td>Beer: visible on POS only, hidden on Kiosk/App</td></tr><tr><td>Delivery markup</td><td>All items: +1000 on App/WhatsApp channels</td></tr><tr><td>Soup not for drive-through</td><td>Soup: fulfillment DRIVE\_THROUGH = unavailable</td></tr><tr><td>Happy hour pricing</td><td>Beer: different price on POS during specific hours</td></tr><tr><td>Dine-in exclusive</td><td>Special dish: fulfillment = DINE\_IN only</td></tr></tbody></table>

---

## Part 13: Data Model Overview

### 13.1 Core Entities

#### Kitchen

- Has many staff members
- Has many menu items
- Has configuration settings
- Has subscription tier and enabled features
- Has many orders, tabs, customers

#### Customer

- Can have App Wallet (platform-wide)
- Can have Kitchen Wallet (kitchen-specific)
- Can have order history
- Identified by phone number or account

#### Tab (PROFESSIONAL+)

- Belongs to a kitchen
- Associated with a table number
- Has many orders
- Has status (OPEN, CLOSED)
- Can have tab-level discounts

#### Order

- Belongs to a kitchen
- Optionally belongs to a tab
- Optionally linked to a customer
- Has many order items
- Has order status and payment status
- Has channel source
- Has fulfillment type
- Has order number (daily reset)
- Has delivery status (for delivery orders)

#### Order Item

- Belongs to an order
- References a menu item
- Has quantity, modifiers, notes
- Has item status (for kitchen tracking)
- Has line total
- Has station assignment (from menu item)

#### Payment

- Linked to an order or tab
- Has payment method
- Has amount and status
- Has reference/confirmation code

#### Receipt

- Generated on payment completion
- Has unique receipt number
- Contains snapshot of transaction
- Immutable (only voided, not modified)

### 13.2 Subscription &amp; Features

```yaml
Kitchen:
  id: uuid
  name: string
  
  subscription:
    plan: STARTER | GROWING | PROFESSIONAL | ENTERPRISE
    status: ACTIVE | TRIAL | PAST_DUE | CANCELLED
    started_at: datetime
    current_period_end: datetime
  
  usage:
    orders_this_month: integer
    menu_items_count: integer
    staff_accounts_count: integer
    locations_count: integer
  
  features: # Derived from plan
    pos_enabled: boolean
    kiosk_enabled: boolean
    table_qr_enabled: boolean
    whatsapp_enabled: boolean
    tabs_enabled: boolean
    stations_enabled: boolean
    kds_enabled: boolean
    drive_through_enabled: boolean
    team_enabled: boolean
    multi_location_enabled: boolean
  
  profile: # From onboarding
    business_type: HOME_KITCHEN | FOOD_STALL | RESTAURANT | CHAIN
    expected_orders_per_day: string
    team_size: string
    service_styles: [DELIVERY, PICKUP, DINE_IN, DRIVE_THROUGH]

```

### 13.3 Entity Relationships

```
Account
├── has many → Kitchens
└── has many → Devices (registered under this account)

Kitchen
├── belongs to → Account
├── has many → Staff
├── has many → Menu Items
├── has many → Customers
├── has many → Orders
├── has many → Tabs
├── has many → Payments
├── has many → Receipts
├── has one → Kitchen Settings
├── has one → Subscription
├── has many → Payment Methods
├── has many → Kitchen Stations
├── has many → Kitchen Printers
└── has many → Devices (assigned to this kitchen)

Station
├── belongs to → Kitchen
├── has many → Menu Items (assigned)
├── has many → KDS Devices (showing this station)
└── has one → Printer (optional dedicated printer)

Device
├── belongs to → Account
├── assigned to → Kitchen (one at a time)
├── assigned to → Station (for KDS, nullable)
└── has → Configuration (fulfillment types, service modes)

Tab
├── belongs to → Kitchen
├── has many → Orders
└── has one → Payment (on close)

Order
├── belongs to → Kitchen
├── belongs to → Tab (optional)
├── belongs to → Customer (optional)
├── has many → Order Items
├── has many → Payments
├── has → Delivery Info (for delivery orders)
└── generates → Receipt

MenuItem
├── belongs to → Kitchen
├── belongs to → Category
├── assigned to → Station
└── has → Channel Settings (visibility, pricing per channel)

```

### 13.4 Order with Delivery Status

For delivery orders, the Order tracks both preparation and delivery status:

```yaml
Order:
  id: uuid
  orderNumber: 47
  kitchenId: uuid
  
  # Core status
  status: CREATED | PENDING_PAYMENT | CONFIRMED | PREPARING | READY | COMPLETED | CANCELLED
  paymentStatus: UNPAID | PENDING | PAID | REFUNDED
  
  # Channel & Fulfillment
  channel: POS | KIOSK | TABLE_QR | APP | WHATSAPP | DRIVE_THROUGH
  fulfillmentType: DINE_IN | PICKUP | DELIVERY | DRIVE_THROUGH
  
  # For DINE_IN
  tableNumber: string (nullable)
  
  # For DRIVE_THROUGH
  laneNumber: integer (nullable)
  vehicleDescription: string (nullable)
  
  # For DELIVERY - Shipping Status
  deliveryStatus: 
    - PENDING           # Waiting for driver assignment
    - DRIVER_ASSIGNED   # Driver accepted
    - DRIVER_ARRIVED    # Driver at restaurant
    - PICKED_UP         # Driver has food
    - IN_TRANSIT        # On the way to customer
    - ARRIVED           # Driver at customer location
    - DELIVERED         # Handed to customer
    - FAILED            # Delivery failed
  
  deliveryProvider: JIKOXPRESS_DASHERS | BOLT | UBER_DIRECT | null
  deliveryExternalId: string (provider's order ID)
  
  driverInfo:
    id: uuid
    name: string
    phone: string
    vehicle: string
    photo: url
    currentLocation: {lat, lng}
    eta: datetime
  
  deliveryAddress:
    street: string
    building: string
    floor: string
    instructions: string
    coordinates: {lat, lng}

```

**Two Parallel Statuses for Delivery Orders:**

- `status` → Kitchen/preparation status (PREPARING → READY)
- `deliveryStatus` → Shipping/logistics status (PICKED\_UP → IN\_TRANSIT → DELIVERED)

---

## Part 14: Unified System Architecture

### 14.1 All Channels, One Kitchen

A single restaurant can enable all channels while sharing the same kitchen and menu:

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           JIKOXPRESS PRO SYSTEM                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ACCOUNT (Owner)                                                            │
│  └── Can own multiple kitchens                                              │
│                                                                             │
│      ┌─────────────────────────────────────────────────────────────────┐   │
│      │  KITCHEN: Mama Lishe Downtown                                   │   │
│      │  Subscription: PROFESSIONAL                                      │   │
│      ├─────────────────────────────────────────────────────────────────┤   │
│      │                                                                 │   │
│      │  MENU (shared across all channels)                              │   │
│      │  ├── Burger (Hot Line) - 12k base, 13k delivery                │   │
│      │  ├── Salad (Cold Line) - 7.5k all channels                     │   │
│      │  ├── Beer (Bar) - 4k, not on Kiosk                             │   │
│      │  └── ...                                                        │   │
│      │                                                                 │   │
│      │  STATIONS                                                       │   │
│      │  ├── Hot Line                                                   │   │
│      │  ├── Cold Line                                                  │   │
│      │  └── Bar                                                        │   │
│      │                                                                 │   │
│      │  DEVICES                                                        │   │
│      │  ├── POS: POS-Counter-1, POS-Counter-2, POS-DriveThru          │   │
│      │  ├── Tablets: Tablet-Waiter-1, Tablet-Waiter-2                 │   │
│      │  ├── Kiosks: Kiosk-Entrance-1, Kiosk-Entrance-2                │   │
│      │  ├── KDS: KDS-HotLine, KDS-ColdLine, KDS-Bar, KDS-Expeditor    │   │
│      │  └── Displays: Display-Counter, Display-DriveThru              │   │
│      │                                                                 │   │
│      │  EXTERNAL CHANNELS (no device, cloud-based)                    │   │
│      │  ├── Mobile App → Orders via API                               │   │
│      │  ├── WhatsApp Bot → Orders via webhook                         │   │
│      │  └── Table QR → Orders via web/app                             │   │
│      │                                                                 │   │
│      └─────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

```

### 14.2 Order Flow - All Channels to One Kitchen

```
     ┌─────────┐
     │   POS   │──┐
     └─────────┘  │
     ┌─────────┐  │
     │  KIOSK  │──┤
     └─────────┘  │
     ┌─────────┐  │      ┌──────────────┐      ┌─────────────┐
     │TABLE QR │──┼─────▶│    ORDER     │─────▶│   KITCHEN   │
     └─────────┘  │      │   (unified)  │      │  (stations) │
     ┌─────────┐  │      └──────────────┘      └─────────────┘
     │   APP   │──┤                                   │
     └─────────┘  │                                   ▼
     ┌─────────┐  │                            ┌─────────────┐
     │WHATSAPP │──┤                            │    READY    │
     └─────────┘  │                            └─────────────┘
     ┌─────────┐  │                                   │
     │DRIVE-TH │──┘                 ┌────────────────┬┴───────────────┐
     └─────────┘                    ▼                ▼                ▼
                              ┌──────────┐    ┌──────────┐    ┌──────────┐
                              │ Table 7  │    │ Counter  │    │ Lane 1   │
                              │ (waiter) │    │ (pickup) │    │ (window) │
                              └──────────┘    └──────────┘    └──────────┘

```

### 14.3 Kitchen Unified Queue

Kitchen sees ONE unified queue with orders from all channels:

```
┌─────────────────────────────────────────────────────────────────────────────┐
│  KITCHEN DISPLAY (All Orders)                                    2:34 PM    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  #41          │  #42          │  #43          │  #44          │  #45       │
│  📱 APP       │  🖥️ KIOSK     │  📋 POS       │  🚗 DRIVE     │  💬 WHATS  │
│  DELIVERY     │  Table 12     │  Table 7      │  Lane 1       │  PICKUP    │
│  3 min ago    │  2 min ago    │  1 min ago    │  Just now ⚡  │  Just now  │
│───────────────│───────────────│───────────────│───────────────│────────────│
│  1x Burger    │  1x Burger    │  1x Burger    │  1x Burger    │  1x Fish   │
│  1x Salad     │  1x Fries     │  1x Salad     │  1x Fries     │            │
│               │               │  1x Beer      │  1x Coke      │            │
│               │               │               │               │            │
│  [START]      │  [WORKING]    │  [START]      │  [PRIORITY]   │  [START]   │
└─────────────────────────────────────────────────────────────────────────────┘

```

**Key Points:**

- Same menu shared across all channels (with per-channel visibility/pricing)
- Same kitchen queue (channel shown as badge)
- Same stations (items route based on menu setup)
- Different handoff points (table, counter, window, delivery)
- Drive-through flagged as priority (⚡)

---

## Part 15: Delivery Integration (Future)

### 15.1 Multiple Delivery Providers

JikoXpress Pro will support multiple delivery providers:

**Planned Providers:**

- JIKOXPRESS\_DASHERS (own fleet)
- BOLT\_FOOD
- UBER\_DIRECT
- SAFEBODA (East Africa specific)

### 15.2 Kitchen Configuration

```yaml
deliverySettings:
  enabledProviders: [JIKOXPRESS_DASHERS, BOLT_FOOD]
  preferredProvider: JIKOXPRESS_DASHERS
  fallbackProvider: BOLT_FOOD
  autoAssign: true | false

```

### 15.3 Order Delivery Properties

```yaml
Order (when fulfillment = DELIVERY):
  deliveryProvider: string (nullable)
  deliveryExternalId: string (provider's order ID)
  deliveryStatus: FINDING_DRIVER | ASSIGNED | PICKED_UP | DELIVERING | DELIVERED
  driverInfo:
    name: string
    phone: string
    vehicle: string
    eta: datetime

```

---

## Part 16: Operational Scenarios

### 16.1 Home Chef Scenario (STARTER)

```
Context: Mama Lishe cooking from home, delivery only

Setup:
- Downloaded mobile app
- Added 10 dishes with photos
- Set operating hours: 11am - 8pm
- Enabled mobile money payments

Daily Flow:
1. Customer finds Mama Lishe on JikoXpress app
2. Customer orders Ugali + Samaki
3. Customer pays via M-Pesa
4. Mama Lishe gets push notification 📱
5. Mama Lishe taps "Accept" 
6. Mama Lishe cooks, taps "Ready"
7. Customer picks up (or delivery arranged separately)
8. Order completed

No POS, no printer, no complexity. Just phone and cooking.

```

### 16.2 Busy Food Stall Scenario (GROWING)

```
Context: Popular food stall, high lunch traffic

Setup:
- Tablet with POS app
- Kitchen ticket printer
- Receipt printer
- 2 staff accounts

Daily Flow:
1. Customer orders at counter
2. Staff enters order on tablet POS
3. Customer pays cash or mobile money
4. Kitchen ticket prints automatically
5. Receipt prints for customer
6. Customer waits for number
7. Order called when ready

```

### 16.3 Restaurant with Dine-In (PROFESSIONAL)

```
Context: Full restaurant, tables, bar

Setup:
- POS terminals
- KDS in kitchen
- Multiple stations (hot line, cold line, bar)
- Table QR codes on all tables
- Tabs enabled

Scenario A - Waiter Service:
1. Customers seated at Table 7
2. Waiter takes order on POS
3. Selects "Pay Later" → Tab created
4. Orders split to stations on KDS
5. Customers order more drinks (added to tab)
6. Customers request bill
7. Waiter prints bill
8. Customers pay
9. Tab closed, receipt printed

Scenario B - Table QR:
1. Customer scans QR at table
2. Orders on phone (no app needed)
3. Pays via USSD
4. Kitchen receives order with "Table 7"
5. Food delivered to table

```

### 16.4 Drive-Through Scenario (PROFESSIONAL)

```
Context: Fast food with drive-through

Setup:
- Speaker/mic at order point
- POS at order window
- KDS showing drive-through orders with priority
- Single window (pay + pickup)

Flow:
1. Car enters Lane 1
2. Customer orders via speaker
3. Staff enters on POS: "Lane 1, Order #23"
4. Customer drives to window
5. Staff processes payment
6. Kitchen already preparing (priority queue)
7. Order ready, handed to customer
8. Car exits, time logged

Metrics tracked:
- Order time: 45 seconds
- Payment time: 30 seconds
- Pickup wait: 2 minutes
- Total time: 3:15 ✓ (target: < 4 min)

```

### 16.5 Multi-Location Chain (ENTERPRISE)

```
Context: 5 restaurant locations

Setup:
- Central menu management
- Each location has own POS, KDS, printers
- Consolidated reporting dashboard
- Staff managed per location with central oversight

Daily Operations:
- Menu update pushed to all 5 locations
- Each location operates independently
- HQ sees real-time sales across all locations
- End of day: consolidated report generated
- Inventory synced across locations

```

---

## Part 17: Non-Functional Requirements

### 17.1 Performance

- Checkout session creation: &lt; 200ms
- Kitchen notification: &lt; 500ms from trigger
- Print job creation: &lt; 200ms
- KDS refresh: Real-time (&lt; 2s)
- Drive-through order entry: &lt; 30 seconds target

### 17.2 Reliability

- Print job retry on failure
- Payment webhook idempotency
- Offline POS capability (queue and sync)
- KDS fallback to printer if display fails

### 17.3 Scalability

- Support 100+ concurrent orders per kitchen
- Support 10,000+ orders per day per kitchen (enterprise)
- Support 100+ locations per enterprise account

### 17.4 Security

- Payment data encryption
- Staff authentication
- Manager PIN for sensitive operations
- Audit log for all transactions
- Receipt data immutability

---

## Part 18: API Structure Overview

### 18.1 Checkout APIs

- Create checkout session
- Process payment
- Cancel session
- Tab management (find, create, close)

### 18.2 Order APIs

- Create order
- Get order details
- Update order status
- Cancel order
- Void item

### 18.3 Kitchen APIs

- Get pending orders (by station)
- Update item/order status
- Fire order (expeditor)

### 18.4 Payment APIs

- Get payment status
- Confirm manual payment
- Handle webhooks
- Request refund

### 18.5 Print APIs

- Get pending print jobs
- Claim/complete/fail print job
- Manual reprint triggers

### 18.6 Subscription APIs

- Get current plan
- Get feature flags
- Get usage stats
- Upgrade/downgrade plan
- Unlock feature module

### 18.7 Device APIs

- Register device
- Get device configuration
- Update device settings
- Device heartbeat
- List devices for kitchen

### 18.8 Station APIs

- Create station
- Update station
- Delete station
- Assign menu items to station
- Assign KDS to station

---

## Appendix A: Glossary

<table id="bkmrk-term-definition-tab-"><thead><tr><th>Term</th><th>Definition</th></tr></thead><tbody><tr><td>Tab</td><td>Container for unpaid orders at a dine-in table</td></tr><tr><td>Stub</td><td>Small printed slip with order number</td></tr><tr><td>KDS</td><td>Kitchen Display System - digital order screens</td></tr><tr><td>Expeditor</td><td>Senior staff controlling order flow</td></tr><tr><td>Station</td><td>Specific preparation area in kitchen</td></tr><tr><td>Bump</td><td>Mark order complete on KDS</td></tr><tr><td>Fire</td><td>Send order to kitchen for preparation</td></tr><tr><td>Void</td><td>Cancel an item from an order</td></tr><tr><td>Kitchen Wallet</td><td>Prepaid balance issued by kitchen</td></tr><tr><td>App Wallet</td><td>Platform-wide customer wallet</td></tr><tr><td>Lane</td><td>Drive-through vehicle queue</td></tr><tr><td>Device</td><td>Registered hardware (POS, Kiosk, KDS, Tablet, Display)</td></tr><tr><td>Channel</td><td>Source of order (POS, Kiosk, App, WhatsApp, etc.)</td></tr><tr><td>Fulfillment</td><td>How order is delivered (Dine-in, Pickup, Delivery, Drive-through)</td></tr><tr><td>Service Mode</td><td>POS operation style (Counter Service, Table Service)</td></tr><tr><td>Delivery Status</td><td>Shipping progress for delivery orders</td></tr><tr><td>Account</td><td>Owner entity that can have multiple kitchens</td></tr><tr><td>Customer Facing Screen</td><td>Display at POS showing cart to customer</td></tr><tr><td>Menu Board</td><td>Digital display showing menu items and prices</td></tr><tr><td>Order Status Display</td><td>Screen showing preparing/ready orders</td></tr><tr><td>Queue Display</td><td>Screen showing "Now Serving" numbers</td></tr></tbody></table>

---

## Appendix B: Configuration Checklist

### STARTER Setup

- [ ]  Download mobile app
- [ ]  Set business name and logo
- [ ]  Add menu items (up to 20)
- [ ]  Set operating hours
- [ ]  Enable mobile money

### GROWING Setup (+ STARTER)

- [ ]  Set up POS on tablet/desktop
- [ ]  Configure kitchen printer
- [ ]  Configure receipt printer
- [ ]  Add staff accounts (up to 3)
- [ ]  Enable additional payment methods
- [ ]  Generate Table QR codes

### PROFESSIONAL Setup (+ GROWING)

- [ ]  Define kitchen stations
- [ ]  Set up KDS displays
- [ ]  Configure station assignments for menu items
- [ ]  Enable tabs
- [ ]  Set staff roles and discount limits
- [ ]  Configure drive-through (if applicable)

### ENTERPRISE Setup (+ PROFESSIONAL)

- [ ]  Add additional locations
- [ ]  Configure central menu
- [ ]  Set up consolidated reporting
- [ ]  Configure API access
- [ ]  Set up inventory tracking

---

## Appendix C: Decision Log

<table id="bkmrk-decision-choice-rati"><thead><tr><th>Decision</th><th>Choice</th><th>Rationale</th></tr></thead><tbody><tr><td>Credit system (Kwa Deni)</td><td>Removed</td><td>Complexity vs V1 scope</td></tr><tr><td>Tab creation</td><td>Auto on first pay-later</td><td>Less friction for staff</td></tr><tr><td>Partial payments</td><td>Defer to V2</td><td>Complexity vs actual need</td></tr><tr><td>Drive-through</td><td>Channel + Fulfillment</td><td>Unified model, same order entity</td></tr><tr><td>Feature unlocking</td><td>Subscription-based</td><td>Clear value tiers, simple UX</td></tr><tr><td>Default config</td><td>Zero-config works</td><td>Reduce onboarding friction</td></tr><tr><td>Print architecture</td><td>Client pull</td><td>Local printer support, offline</td></tr><tr><td>Order number</td><td>Daily reset</td><td>Easier for kitchen communication</td></tr><tr><td>Platform scale</td><td>One codebase all tiers</td><td>Same APIs, feature flags gate access</td></tr><tr><td>Device registration</td><td>Email + code + kitchen select</td><td>Secure, supports multi-kitchen accounts</td></tr><tr><td>One device one kitchen</td><td>Must logout to switch</td><td>Simplifies operations, prevents confusion</td></tr><tr><td>Station assignment</td><td>Pre-defined in menu setup</td><td>Automatic routing, no manual selection</td></tr><tr><td>Menu channel settings</td><td>Per-channel visibility/pricing</td><td>Flexibility for delivery markup, restrictions</td></tr><tr><td>Delivery status</td><td>Separate from order status</td><td>Two parallel tracking (kitchen vs shipping)</td></tr><tr><td>POS service modes</td><td>Counter vs Table service</td><td>Same device, different workflows</td></tr></tbody></table>

---

## Document History

<table id="bkmrk-version-date-changes"><thead><tr><th>Version</th><th>Date</th><th>Changes</th></tr></thead><tbody><tr><td>1.0</td><td>December 2025</td><td>Initial document</td></tr><tr><td>2.0</td><td>January 2026</td><td>Removed Kwa Deni, added Drive-Through, added Progressive Feature Unlocking, added Subscription Tiers, added Default Configuration, noted Multi-Provider Delivery</td></tr><tr><td>2.1</td><td>January 2026</td><td>Added Device Management (registration, types, configuration), expanded Station architecture (creation, assignment, routing), added Menu Channel Settings (per-channel visibility/pricing), added POS Service Modes (counter vs table service), added Order Delivery Status tracking, added Unified System Architecture diagrams</td></tr></tbody></table>

---

*End of Document*

# Checkout ReqSample Senarials

# JikoXpress — Checkout Session API Scenarios

> Version 1.0 | April 2026 | QBIT SPARK CO LIMITED  
> Reference guide for all checkout session creation scenarios

---

## Overview

A checkout session is a **temporary stepping stone** to an order. Once confirmed, the session creates an order and its job is done. Sessions are never refunded — orders are.

### Session Types

<table id="bkmrk-type-description-imm"><thead><tr><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>`IMMEDIATE`</td><td>Pay now, right at this terminal</td></tr><tr><td>`SLIP`</td><td>Generate slip, customer goes to cashier</td></tr><tr><td>`TAB`</td><td>Pay later, dine-in rounds</td></tr></tbody></table>

### Session Statuses

<table id="bkmrk-status-description-p"><thead><tr><th>Status</th><th>Description</th></tr></thead><tbody><tr><td>`PENDING_PAYMENT`</td><td>Waiting for payment — USSD webhook or cashier confirmation</td></tr><tr><td>`CONFIRMED`</td><td>Payment done, order created</td></tr><tr><td>`EXPIRED`</td><td>Slip timed out, inventory released</td></tr><tr><td>`CANCELLED`</td><td>Manually cancelled, inventory released</td></tr><tr><td>`FAILED`</td><td>Payment failed, inventory released</td></tr></tbody></table>

### Payment Methods

<table id="bkmrk-method-description-c"><thead><tr><th>Method</th><th>Description</th></tr></thead><tbody><tr><td>`CASH`</td><td>Physical money</td></tr><tr><td>`MOBILE_MONEY`</td><td>USSD — M-Pesa, Tigo, Airtel</td></tr><tr><td>`CARD`</td><td>Visa, Mastercard</td></tr><tr><td>`PLATFORM_WALLET`</td><td>JikoXpress app wallet</td></tr><tr><td>`KITCHEN_WALLET`</td><td>Kitchen issued prepaid balance</td></tr><tr><td>`KITCHEN_CHANNEL`</td><td>Kitchen configured channel — Lipa Voda, HaloPesa etc</td></tr></tbody></table>

---

## Instructions

<table id="bkmrk-level-field-use-case"><thead><tr><th>Level</th><th>Field</th><th>Use Case</th></tr></thead><tbody><tr><td>Session</td><td>`orderInstructions`</td><td>One note for whole order — POS, Kiosk, Dine-in</td></tr><tr><td>Item</td><td>`itemInstructions`</td><td>Per item note — App, mixed kitchen orders</td></tr></tbody></table>

Both can be used together. Session instruction goes to kitchen as a general note. Item instruction travels with that specific item.

---

## Channel &amp; Fulfillment Matrix

<table id="bkmrk-channel-dine_in-pick"><thead><tr><th>Channel</th><th>DINE\_IN</th><th>PICKUP</th><th>DELIVERY</th><th>DRIVE\_THROUGH</th></tr></thead><tbody><tr><td>`POS`</td><td>✅</td><td>✅</td><td>❌</td><td>✅</td></tr><tr><td>`KIOSK`</td><td>✅</td><td>✅</td><td>❌</td><td>❌</td></tr><tr><td>`TABLE_QR`</td><td>✅</td><td>❌</td><td>❌</td><td>❌</td></tr><tr><td>`APP`</td><td>❌</td><td>✅</td><td>✅</td><td>❌</td></tr><tr><td>`WHATSAPP`</td><td>❌</td><td>✅</td><td>✅</td><td>❌</td></tr></tbody></table>

> Server rejects any combination not in this matrix with a clear error message.

---

### POS — Dine In, Pay Now

Customer sits at table, pays immediately — no tab opened.

```json
{
  "sessionType": "IMMEDIATE",
  "channel": "POS",
  "fulfillmentType": "DINE_IN",
  "tableNumber": "05",
  "tag": "John",
  "items": [
    {"menuId": "uuid", "quantity": 1, "itemInstructions": null}
  ],
  "payments": [
    {
      "paymentMethod": "CASH",
      "amount": 5000
    }
  ]
}

```

---

### POS — Drive Through, Pay Now

Customer in lane, staff takes order at window, pays immediately.

```json
{
  "sessionType": "IMMEDIATE",
  "channel": "POS",
  "fulfillmentType": "DRIVE_THROUGH",
  "laneNumber": "1",
  "tag": "Red Toyota",
  "items": [
    {"menuId": "uuid", "quantity": 2, "itemInstructions": null},
    {"menuId": "uuid", "quantity": 1, "itemInstructions": "no onions"}
  ],
  "payments": [
    {
      "paymentMethod": "CASH",
      "amount": 8000
    }
  ]
}

```

---

### POS — Drive Through, Generate Slip

Customer in lane, staff takes order, generates slip. Customer drives to payment window.

```json
{
  "sessionType": "SLIP",
  "channel": "POS",
  "fulfillmentType": "DRIVE_THROUGH",
  "laneNumber": "1",
  "tag": "Blue Corolla",
  "items": [
    {"menuId": "uuid", "quantity": 1, "itemInstructions": null}
  ]
}

```

---

### Kiosk — Dine In, Cash Slip

Customer at kiosk inside restaurant, orders for their table, pays cash at counter.

```json
{
  "sessionType": "SLIP",
  "channel": "KIOSK",
  "fulfillmentType": "DINE_IN",
  "tableNumber": "03",
  "items": [
    {"menuId": "uuid", "quantity": 2, "itemInstructions": null}
  ]
}

```

---

### Kiosk — Dine In, Mobile Money

Customer at kiosk, orders for their table, pays USSD immediately.

```json
{
  "sessionType": "IMMEDIATE",
  "channel": "KIOSK",
  "fulfillmentType": "DINE_IN",
  "tableNumber": "03",
  "items": [
    {"menuId": "uuid", "quantity": 1, "itemInstructions": null}
  ],
  "payments": [
    {
      "paymentMethod": "MOBILE_MONEY",
      "amount": 5000
    }
  ]
}

```

---

### App — Pickup, Platform Wallet

App user orders pickup, pays with JikoXpress platform wallet.

```json
{
  "sessionType": "IMMEDIATE",
  "channel": "APP",
  "fulfillmentType": "PICKUP",
  "kitchenId": "uuid",
  "fromCart": false,
  "items": [
    {"menuId": "uuid", "quantity": 1, "itemInstructions": null}
  ],
  "payments": [
    {
      "paymentMethod": "PLATFORM_WALLET",
      "amount": 5000
    }
  ]
}

```

---

### WhatsApp — Pickup

Customer orders via WhatsApp, will collect food themselves.

```json
{
  "sessionType": "IMMEDIATE",
  "channel": "WHATSAPP",
  "fulfillmentType": "PICKUP",
  "kitchenId": "uuid",
  "customerPhone": "+255700000000",
  "items": [
    {"menuId": "uuid", "quantity": 1, "itemInstructions": null}
  ],
  "payments": [
    {
      "paymentMethod": "MOBILE_MONEY",
      "amount": 5000
    }
  ]
}

```

---

## IDs Resolved Server Side

These are **never passed in request** — resolved from context:

<table id="bkmrk-field-resolved-from-"><thead><tr><th>Field</th><th>Resolved From</th></tr></thead><tbody><tr><td>`staffId`</td><td>Authenticated staff session token</td></tr><tr><td>`accountId`</td><td>Authenticated JikoXpress user token</td></tr><tr><td>Kitchen (POS/Kiosk)</td><td>Staff session — staff belongs to a kitchen</td></tr><tr><td>Kitchen (App direct)</td><td>Passed in request</td></tr><tr><td>Kitchen (App cart)</td><td>Derived from cart items grouped by kitchen</td></tr></tbody></table>

---

## Payment Split Model

All payments are a list. Single payment = list of one. Amounts must sum to session total.

```json
{
  "payments": [
    {
      "paymentMethod": "KITCHEN_WALLET",
      "kitchenCustomerId": "uuid",
      "amount": 3000
    },
    {
      "paymentMethod": "KITCHEN_CHANNEL",
      "kitchenPaymentMethodId": "uuid",
      "amount": 1500
    },
    {
      "paymentMethod": "MOBILE_MONEY",
      "amount": 1000
    },
    {
      "paymentMethod": "CASH",
      "amount": 500
    },
    {
      "paymentMethod": "CARD",
      "amount": 500
    },
    {
      "paymentMethod": "PLATFORM_WALLET",
      "amount": 500
    }
  ]
}

```

> `kitchenCustomerId` required only for `KITCHEN_WALLET`  
> `kitchenPaymentMethodId` required only for `KITCHEN_CHANNEL`

---

## Scenarios

---

### 1. POS — Pay Now, Cash

Staff takes order at counter. Customer pays cash immediately.

```json
{
  "sessionType": "IMMEDIATE",
  "channel": "POS",
  "fulfillmentType": "PICKUP",
  "tag": "John",
  "orderInstructions": null,
  "items": [
    {"menuId": "uuid", "quantity": 2, "itemInstructions": null},
    {"menuId": "uuid", "quantity": 1, "itemInstructions": "no salt"}
  ],
  "payments": [
    {
      "paymentMethod": "CASH",
      "amount": 5000
    }
  ]
}

```

---

### 2. POS — Pay Now, Split Payment

Customer pays part cash, part mobile money.

```json
{
  "sessionType": "IMMEDIATE",
  "channel": "POS",
  "fulfillmentType": "PICKUP",
  "tag": "Sarah",
  "items": [
    {"menuId": "uuid", "quantity": 1, "itemInstructions": null}
  ],
  "payments": [
    {
      "paymentMethod": "CASH",
      "amount": 2000
    },
    {
      "paymentMethod": "MOBILE_MONEY",
      "amount": 3000
    }
  ]
}

```

---

### 3. POS — Pay Now, Kitchen Wallet

Loyal customer pays using their prepaid kitchen wallet.

```json
{
  "sessionType": "IMMEDIATE",
  "channel": "POS",
  "fulfillmentType": "PICKUP",
  "tag": "Mama Fatuma",
  "items": [
    {"menuId": "uuid", "quantity": 2, "itemInstructions": null}
  ],
  "payments": [
    {
      "paymentMethod": "KITCHEN_WALLET",
      "kitchenCustomerId": "uuid",
      "amount": 5000
    }
  ]
}

```

---

### 4. POS — Pay Now, Kitchen Channel (Lipa Voda)

Customer pays via kitchen configured channel e.g. Vodacom Lipa.

```json
{
  "sessionType": "IMMEDIATE",
  "channel": "POS",
  "fulfillmentType": "PICKUP",
  "tag": "James",
  "items": [
    {"menuId": "uuid", "quantity": 1, "itemInstructions": null}
  ],
  "payments": [
    {
      "paymentMethod": "KITCHEN_CHANNEL",
      "kitchenPaymentMethodId": "uuid",
      "amount": 5000
    }
  ]
}

```

---

### 5. POS — Generate Slip (Human Kiosk)

Staff takes order, generates slip. Customer walks to cashier to pay.

```json
{
  "sessionType": "SLIP",
  "channel": "POS",
  "fulfillmentType": "PICKUP",
  "tag": "John",
  "orderInstructions": null,
  "items": [
    {"menuId": "uuid", "quantity": 1, "itemInstructions": "no salt"}
  ]
}

```

> No `payments` — cashier will collect when customer brings slip

---

### 6. POS — Tab, Round 1 (New Bill)

Dine-in customer. Staff opens new tab/bill for the table.

```json
{
  "sessionType": "TAB",
  "channel": "POS",
  "fulfillmentType": "DINE_IN",
  "tableNumber": "05",
  "tag": "Family ya Mbeya",
  "items": [
    {"menuId": "uuid", "quantity": 2, "itemInstructions": null},
    {"menuId": "uuid", "quantity": 1, "itemInstructions": "extra spicy"}
  ]
}

```

> No `billId` — server creates new `KitchenBillsEntity` automatically  
> No `payments` — customer pays at end

---

### 7. POS — Tab, Round 2 (Existing Bill)

Same table orders more. Cashier picks existing open bill, adds new round.

```json
{
  "sessionType": "TAB",
  "channel": "POS",
  "fulfillmentType": "DINE_IN",
  "tableNumber": "05",
  "billId": "existing-bill-uuid",
  "items": [
    {"menuId": "uuid", "quantity": 2, "itemInstructions": null}
  ]
}

```

> `billId` links this round to the existing open bill  
> New kitchen ticket fires for these items only

---

### 8. Kiosk Machine — Cash Slip

Customer self-orders on kiosk machine. Chooses to pay cash. Slip prints. Customer walks to cashier.

```json
{
  "sessionType": "SLIP",
  "channel": "KIOSK",
  "fulfillmentType": "PICKUP",
  "items": [
    {"menuId": "uuid", "quantity": 2, "itemInstructions": null},
    {"menuId": "uuid", "quantity": 1, "itemInstructions": null}
  ]
}

```

> `kitchenId` derived from kiosk device registration  
> Slip expires after configured time (default 15 min)

---

### 9. Kiosk Machine — Mobile Money (Immediate)

Customer self-orders on kiosk, pays via USSD immediately.

```json
{
  "sessionType": "IMMEDIATE",
  "channel": "KIOSK",
  "fulfillmentType": "PICKUP",
  "items": [
    {"menuId": "uuid", "quantity": 1, "itemInstructions": null}
  ],
  "payments": [
    {
      "paymentMethod": "MOBILE_MONEY",
      "amount": 5000
    }
  ]
}

```

> Session stays `PENDING_PAYMENT` until USSD webhook confirms

---

### 10. Table QR — Pay on Phone

Customer scans QR at table, orders, pays via USSD on their own phone.

```json
{
  "sessionType": "IMMEDIATE",
  "channel": "TABLE_QR",
  "fulfillmentType": "DINE_IN",
  "tableNumber": "05",
  "items": [
    {"menuId": "uuid", "quantity": 1, "itemInstructions": null}
  ],
  "payments": [
    {
      "paymentMethod": "MOBILE_MONEY",
      "amount": 5000
    }
  ]
}

```

> `kitchenId` embedded in QR code, resolved server side  
> Needs cashier approval before going to kitchen

---

### 11. Table QR — Pay at Cashier (Slip)

Customer scans QR, orders, chooses to pay cash at counter.

```json
{
  "sessionType": "SLIP",
  "channel": "TABLE_QR",
  "fulfillmentType": "DINE_IN",
  "tableNumber": "05",
  "items": [
    {"menuId": "uuid", "quantity": 1, "itemInstructions": null}
  ]
}

```

---

### 12. App — Checkout from Cart, Delivery

App user checks out all items from their cart. One payment, orders split per kitchen automatically.

```json
{
  "sessionType": "IMMEDIATE",
  "channel": "APP",
  "fulfillmentType": "DELIVERY",
  "fromCart": true,
  "deliveryAddress": {
    "street": "Lumumba St",
    "area": "Mbeya",
    "city": "Mbeya",
    "notes": "Green gate",
    "latitude": -8.9,
    "longitude": 33.4
  },
  "payments": [
    {
      "paymentMethod": "MOBILE_MONEY",
      "amount": 15000
    }
  ]
}

```

> `accountId` from auth token  
> `kitchenId` derived from cart items — one session created per kitchen  
> `fromCart: true` — no `items` needed in request

---

### 13. App — Direct Buy, No Cart

App user buys directly from a kitchen without going through cart.

```json
{
  "sessionType": "IMMEDIATE",
  "channel": "APP",
  "fulfillmentType": "DELIVERY",
  "kitchenId": "uuid",
  "fromCart": false,
  "items": [
    {"menuId": "uuid", "quantity": 1, "itemInstructions": null}
  ],
  "deliveryAddress": {
    "street": "Lumumba St",
    "area": "Mbeya",
    "city": "Mbeya",
    "notes": "Green gate",
    "latitude": -8.9,
    "longitude": 33.4
  },
  "payments": [
    {
      "paymentMethod": "PLATFORM_WALLET",
      "amount": 5000
    }
  ]
}

```

> `fromCart: false` — items passed directly in request  
> `kitchenId` required since not derived from cart

---

### 14. WhatsApp — Delivery

Customer orders via WhatsApp chatbot. Not a JikoXpress user — identified by phone number only.

```json
{
  "sessionType": "IMMEDIATE",
  "channel": "WHATSAPP",
  "fulfillmentType": "DELIVERY",
  "kitchenId": "uuid",
  "customerPhone": "+255700000000",
  "items": [
    {"menuId": "uuid", "quantity": 1, "itemInstructions": null},
    {"menuId": "uuid", "quantity": 2, "itemInstructions": "extra sauce"}
  ],
  "deliveryAddress": {
    "street": "Lumumba St",
    "area": "Mbeya",
    "city": "Mbeya",
    "notes": "Green gate",
    "latitude": -8.9,
    "longitude": 33.4
  },
  "payments": [
    {
      "paymentMethod": "MOBILE_MONEY",
      "amount": 8000
    }
  ]
}

```

> `kitchenId` from chatbot — each kitchen has their own WhatsApp number  
> `customerPhone` identifies customer — no JikoXpress account needed  
> No `accountId` — WhatsApp customer is anonymous to platform

---

## Edge Cases

---

### Kitchen Wallet — Insufficient Balance, Split with Cash

Customer's kitchen wallet has 3000 but total is 5000. Pays difference with cash.

```json
{
  "sessionType": "IMMEDIATE",
  "channel": "POS",
  "fulfillmentType": "PICKUP",
  "items": [
    {"menuId": "uuid", "quantity": 2, "itemInstructions": null}
  ],
  "payments": [
    {
      "paymentMethod": "KITCHEN_WALLET",
      "kitchenCustomerId": "uuid",
      "amount": 3000
    },
    {
      "paymentMethod": "CASH",
      "amount": 2000
    }
  ]
}

```

---

### Three-Way Split

Customer splits across cash, kitchen channel, and mobile money.

```json
{
  "sessionType": "IMMEDIATE",
  "channel": "POS",
  "fulfillmentType": "PICKUP",
  "items": [
    {"menuId": "uuid", "quantity": 3, "itemInstructions": null}
  ],
  "payments": [
    {
      "paymentMethod": "CASH",
      "amount": 2000
    },
    {
      "paymentMethod": "KITCHEN_CHANNEL",
      "kitchenPaymentMethodId": "uuid",
      "amount": 2000
    },
    {
      "paymentMethod": "MOBILE_MONEY",
      "amount": 1000
    }
  ]
}

```

---

### Tab — Pay Bill with Split

Customer finishes eating, pays open tab with card and cash.

> This happens at **bill close time**, not session creation.  
> Separate endpoint: `POST /bills/{billId}/pay`

```json
{
  "payments": [
    {
      "paymentMethod": "CARD",
      "amount": 10000
    },
    {
      "paymentMethod": "CASH",
      "amount": 5000
    }
  ]
}

```

---

### Cashier Confirms Slip Payment

Customer arrives at counter with slip. Cashier scans barcode or finds slip by number. Confirms cash collected. Order created and sent to kitchen.

> Endpoint: `POST /checkout-sessions/{sessionId}/confirm-slip`

```json
{
  "payments": [
    {
      "paymentMethod": "CASH",
      "amount": 5000
    }
  ]
}

```

> Cashier can also split payment at this point — customer may pay slip with mobile money instead of cash

---

### Cashier Confirms Slip — Split Payment

Customer brought slip but wants to pay part cash, part mobile money.

> Endpoint: `POST /checkout-sessions/{sessionId}/confirm-slip`

```json
{
  "payments": [
    {
      "paymentMethod": "CASH",
      "amount": 3000
    },
    {
      "paymentMethod": "MOBILE_MONEY",
      "amount": 2000
    }
  ]
}

```

> After confirmation → session `CONFIRMED` → order created → kitchen notified → inventory deducted

---

*QBIT SPARK CO LIMITED | JikoXpress | April 2026*  
*Internal development reference — confidential*