JikoXpress DishMng
- JikoXpress Pro - Menu & Dish Management System
- JikoXpress Pro: Checkout & Order Management Architecture
- Checkout ReqSample Senarials
JikoXpress Pro - Menu & Dish Management System
Version: 1.0
Target Market: East African Restaurant Industry
System Type: Kitchen Management System with Component-Based Inventory
1. System Overview
JikoXpress Pro is a comprehensive restaurant kitchen management system designed specifically for the East African market. The system provides component-based inventory tracking, flexible menu scheduling, comprehensive waste management, and detailed profit analytics.
Core Philosophy: Track everything at the component (dish) level, regardless of how items are sold - standalone, in combos, or custom builds.
2. Core Concepts
2.1 Dish (Component)
The fundamental building block of the entire system. A dish is any individual food item that can be:
- Sold standalone
- Combined into menu schedules
- Tracked in inventory
- Used in custom builds
Dish Properties
| Property | Type | Description |
|---|---|---|
id |
UUID | Unique identifier |
name |
String | Display name (e.g., "Ugali", "Maharage") |
prepCost |
BigDecimal | Cost to prepare one portion |
sellingPrice |
BigDecimal | Standalone selling price |
currentInventory |
Integer | Available portions |
canSellStandalone |
Boolean | Whether item can be sold individually |
imageUrl |
String | Required dish photo |
thumbnailUrl |
String | Auto-generated thumbnail |
active |
Boolean | Whether dish is available |
Dish Examples
Dish: Ugali
- prepCost: 100 TSH
- sellingPrice: 300 TSH
- canSellStandalone: true
Dish: Maharage (Beans)
- prepCost: 200 TSH
- sellingPrice: 400 TSH
- canSellStandalone: true
Dish: Chai (Tea)
- prepCost: 20 TSH
- sellingPrice: 100 TSH
- canSellStandalone: true
Important: Dishes do NOT have time-based visibility. Time visibility is handled at the Menu Schedule level only.
2.2 Menu Schedule
Pre-defined combinations of dishes with time-based visibility and promotional pricing.
Menu Schedule Properties
| Property | Type | Description |
|---|---|---|
id |
UUID | Unique identifier |
name |
String | Display name (e.g., "Lunch Special") |
components |
List<Dish> | Dishes included in this menu |
componentCost |
BigDecimal | Auto-calculated from components |
sellingPrice |
BigDecimal | Manually set (can be promotional) |
category |
Enum | MAIN_FOOD, DRINKS, SNACKS, DESSERTS |
session |
Enum | BREAKFAST, LUNCH, DINNER, ALL_DAY |
scheduleType |
Enum | ONE_TIME, DAILY, WEEKLY, PERMANENT |
menuType |
Enum | COMBO, INDIVIDUAL_ITEM |
visibleFrom |
LocalTime | Start time for visibility |
visibleUntil |
LocalTime | End time for visibility |
activeDays |
Set<DayOfWeek> | For recurring schedules |
validFrom |
LocalDate | Start date validity |
validUntil |
LocalDate | End date validity |
active |
Boolean | Master on/off switch |
heroImageUrl |
String | Optional custom combo image |
Key Concepts
1. Category vs Session:
Category (Product Type): Session (Time Slot):
- MAIN_FOOD - BREAKFAST (6am-10am)
- DRINKS - LUNCH (12pm-3pm)
- SNACKS - DINNER (6pm-9pm)
- DESSERTS - ALL_DAY
2. Schedule Types:
ONE_TIME: Special event menu (e.g., "New Year Special")
DAILY: Repeats every day within time window
WEEKLY: Repeats on specific days (e.g., Mon-Fri only)
PERMANENT: Always available (within time window)
COMBO: Multiple components (e.g., Ugali + Maharage)
INDIVIDUAL_ITEM: Single component as menu item (e.g., standalone Chai)
Menu Schedule Examples
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%)
Name: "Chai"
Components: [Chai]
Category: DRINKS
Session: BREAKFAST
Schedule Type: DAILY
Menu Type: INDIVIDUAL_ITEM
Visible: 06:00 - 10:00
Component Cost: 20 TSH
Selling Price: 100 TSH
Profit Margin: 80 TSH
2.3 Selling Price Strategy
Critical Design Decision: Selling prices exist at BOTH levels.
Where Prices Are Set
| Level | Purpose | Example |
|---|---|---|
| Dish Level | Standalone/custom build sales | Ugali = 300 TSH |
| Menu Schedule Level | Combo/promotional pricing | "Ugali + Maharage" = 600 TSH |
Price Usage Rules
Flow 1: Customer orders Menu Schedule
→ Use MENU price (600 TSH)
→ Allocate revenue proportionally to components
Flow 2: Customer orders standalone dish
→ Use DISH price (300 TSH)
→ Full revenue to that dish
Flow 3: Custom build
→ Sum of DISH prices (300 + 400 = 700 TSH)
→ Each component gets full price
Same Components, Different Prices
Scenario Price Source Amount
─────────────────────────────────────────────────────────
"Ugali + Maharage Special" Menu 600 TSH
Ugali standalone Dish 300 TSH
Maharage standalone Dish 400 TSH
Custom: Ugali + Maharage Sum of Dishes 700 TSH
2.4 Dish Pairing (Smart Sides)
Dish pairings power the Smart Sides popup in the counter app. They define which sides appear when a main dish is selected.
Pairing Properties
| Property | Type | Description |
|---|---|---|
id |
UUID | Unique identifier |
mainDish |
Dish | The main dish (e.g., Ugali) |
sideDish |
Dish | The suggested side (e.g., Maharage) |
combo |
MenuSchedule | Linked combo if exists (nullable) |
source |
Enum | COMBO, BEHAVIOR, MANUAL |
orderCount |
Integer | Times ordered together |
savings |
BigDecimal | Discount if combo exists |
displayOrder |
Integer | Sort priority in popup |
active |
Boolean | Whether to show in popup |
Pairing Sources
| Source | Description | Badge in UI |
|---|---|---|
| COMBO | Derived from existing MenuSchedules | 💰 SAVE X |
| BEHAVIOR | Learned from customer order patterns | 🔥 Popular |
| MANUAL | Admin-defined suggestions | (none) |
How Pairings Are Generated
Source 1: From Existing Combos
System automatically scans all MenuSchedules and creates pairings.
MenuSchedule: "Ugali Maharage" (Ugali + Maharage)
→ Creates pairing: Ugali → Maharage (source: COMBO, savings: 100)
MenuSchedule: "Ugali Nyama" (Ugali + Nyama)
→ Creates pairing: Ugali → Nyama (source: COMBO, savings: 150)
Source 2: From Customer Behavior
System analyzes custom build orders to find frequent pairings.
Analysis finds:
- Ugali + Kachumbari ordered 47 times (no combo exists)
→ Creates pairing: Ugali → Kachumbari (source: BEHAVIOR, orderCount: 47)
- Chapati + Maharage ordered 32 times (no combo exists)
→ Creates pairing: Chapati → Maharage (source: BEHAVIOR, orderCount: 32)
Source 3: Manual Admin Entry
Admin can manually add pairings for strategic suggestions.
Admin adds:
- Chips → Kachumbari (always suggest salad with chips)
→ Creates pairing: Chips → Kachumbari (source: MANUAL)
Popup Display Priority
When showing the Smart Sides popup, pairings are sorted:
- COMBO pairings first (sorted by savings, highest first)
- BEHAVIOR pairings second (sorted by orderCount, highest first)
- MANUAL pairings last (sorted by displayOrder)
2.5 Behavior Learning System
The system continuously learns from customer orders to improve suggestions.
What It Tracks
For every custom build order, the system records:
- Which main dish was selected
- Which sides were paired with it
- Date and time of order
- Restaurant location (for multi-location)
Learning Rules
| Rule | Threshold | Action |
|---|---|---|
| Minimum orders | 10+ times | Consider for pairing |
| Time window | Last 30 days | Recent behavior only |
| Already exists | Skip | Don't duplicate pairings |
| Combo created | Convert | Change source to COMBO |
Admin Insights
The system surfaces learned pairings to admins with recommendations:
Suggested New Combos
🔥 Ugali + Kachumbari
Ordered together 47 times this month
No combo exists
Potential monthly revenue if combo created: +12,000 TSH
[Create Combo] [Ignore] [Hide]
Underperforming Combos
⚠️ Wali + Samaki
Only 3 orders this month
Combo exists but rarely used
[Promote] [Deactivate] [Keep]
3. Order Flow & Sales Tracking
3.1 Order Entity Structure
Order
├── id: UUID
├── orderNumber: String (auto-generated)
├── orderType: MENU_SCHEDULE | CUSTOM_BUILD | STANDALONE
├── subtotal: BigDecimal
├── discountType: PERCENTAGE | FIXED_AMOUNT | PROMO_CODE | MANAGER_OVERRIDE
├── discountValue: BigDecimal
├── discountAmount: BigDecimal
├── total: BigDecimal
├── paymentMethod: CASH | MOBILE_MONEY
├── status: PENDING | COMPLETED | CANCELLED
├── createdBy: Staff
├── createdAt: LocalDateTime
└── items: List<OrderItem>
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)
Allocation Formula
Component Allocation = Menu Price × (Component Standalone Price / Total Standalone Prices)
Allocation Example
Menu: "Ugali + Maharage Special"
Selling Price: 600 TSH
Components:
- Ugali standalone: 300 TSH
- Maharage standalone: 400 TSH
Total standalone: 700 TSH
Allocation:
- Ugali: 600 × (300/700) = 600 × 0.4286 = 257.14 TSH
- Maharage: 600 × (400/700) = 600 × 0.5714 = 342.86 TSH
Total: 600 TSH ✓
Why Proportional?
Restaurant owners need to see profit/loss per item. Proportional allocation ensures:
- Each item gets same percentage discount as the combo offers
- Fair distribution based on relative value
- Accurate item-level profitability reporting
4. Discount System
4.1 Discount Structure
Design Decision: Order-level discounts only (not item-level).
Discount Types
| Type | Description | Example |
|---|---|---|
PERCENTAGE |
Percentage off total | 10% off |
FIXED_AMOUNT |
Fixed amount off | 200 TSH off |
PROMO_CODE |
Promotional code | "LUNCH10" |
MANAGER_OVERRIDE |
Manual discount with reason | Customer complaint |
STAFF_MEAL |
100% discount for staff | Employee meal |
ROUNDING |
Cash rounding adjustment | Round to 50/100 |
4.2 Discount Application
Discounts are distributed proportionally to all items.
Example
Order:
- Ugali + Maharage Special: 600 TSH
- Wali + Nyama: 800 TSH
- Chai: 100 TSH
Subtotal: 1,500 TSH
Discount: 10% = 150 TSH
Distribution (same % to each):
- Ugali + Maharage: 600 - 60 = 540 TSH (10% off)
- Wali + Nyama: 800 - 80 = 720 TSH (10% off)
- Chai: 100 - 10 = 90 TSH (10% off)
Total: 1,350 TSH ✓
4.3 Counter App Discount Flow
┌─────────────────────────────────┐
│ Current Order │
├─────────────────────────────────┤
│ Ugali + Maharage Special 600 │
│ Chai 100 │
│ │
│ Subtotal: 700 │
│ │
│ [💰 Apply Discount] │
│ [✅ Complete Order] │
└─────────────────────────────────┘
↓ Tap Apply Discount
┌─────────────────────────────────┐
│ Apply Discount │
├─────────────────────────────────┤
│ Type: │
│ ○ Percentage (%) │
│ ○ Fixed Amount (TSH) │
│ ○ Promo Code │
│ │
│ Value: [10] % │
│ │
│ Reason: [Customer complaint___] │
│ │
│ Preview: │
│ Subtotal: 700 │
│ Discount: -70 │
│ ═══════════════════════ │
│ Total: 630 ✓ │
│ │
│ [Cancel] [Apply] │
└─────────────────────────────────┘
4.4 Cash Rounding (Tanzania Specific)
Tanzania uses cash denominations (50/100 TSH coins). System handles rounding.
Rounding Options
Calculated Total: 315 TSH
Options:
1. Round to nearest 50: 300 TSH (customer saves 15)
2. Round to nearest 100: 300 TSH (customer saves 15)
3. Staff adjustment: Apply -15 discount
4. Credit to wallet: 15 TSH for next order
Mobile Money
No rounding needed - exact amounts supported.
5. Inventory Management
5.1 Component-Level Tracking
Core Principle: All inventory is tracked at the dish (component) level, never at menu level.
How It Works
Sale: "Ugali + Maharage Special"
Inventory Update:
- Ugali: -1 portion
- Maharage: -1 portion
NOT:
- "Ugali + Maharage Special": -1 ← WRONG! No menu-level inventory
5.2 Stock Adjustment System
Three adjustment types with live calculation preview.
Action 1: Prep New Batch
Adds inventory when kitchen prepares food.
┌─────────────────────────────────┐
│ Prep New Batch - Beans │
├─────────────────────────────────┤
│ Quantity prepared: [50] │
│ │
│ ┌─────────────────────────────┐ │
│ │ Calculation Preview: │ │
│ ├─────────────────────────────┤ │
│ │ Current stock: 15 │ │
│ │ Adding: +50 │ │
│ │ ═══════════════════════ │ │
│ │ New stock: 65 ✓ │ │
│ └─────────────────────────────┘ │
│ │
│ Prep cost (optional): [2000] │
│ Prepared by: Chef John (auto) │
│ Time: 8:00 AM (auto) │
│ │
│ [Cancel] [Confirm Prep] │
└─────────────────────────────────┘
Records:
- Quantity prepared
- Prep cost (optional)
- Who prepared
- Timestamp
Action 2: Dump/Waste
Removes inventory with waste tracking.
┌─────────────────────────────────┐
│ Dump/Waste - Ugali │
├─────────────────────────────────┤
│ Quantity to dump: [10] │
│ │
│ ┌─────────────────────────────┐ │
│ │ Calculation Preview: │ │
│ ├─────────────────────────────┤ │
│ │ Current stock: 65 │ │
│ │ Removing: -10 │ │
│ │ ═══════════════════════ │ │
│ │ New stock: 55 ✓ │ │
│ │ Waste value: 400 💸 │ │
│ └─────────────────────────────┘ │
│ │
│ Reason: │
│ ○ Spoiled/Expired │
│ ● Poor quality │
│ ○ Overcooked │
│ ○ Dropped/Accident │
│ ○ End of day dump │
│ ○ Other: [___________] │
│ │
│ Dumped by: Chef Mary (auto) │
│ Time: 2:30 PM (auto) │
│ │
│ [Cancel] [Confirm Dump] │
└─────────────────────────────────┘
Waste Reasons:
- Spoiled/Expired
- Poor quality
- Overcooked
- Dropped/Accident
- End of day dump
- Other (free text)
Action 3: Manual Adjust
General corrections for edge cases.
┌─────────────────────────────────┐
│ Manual Adjust - Rice │
├─────────────────────────────────┤
│ Adjustment type: │
│ ● Add inventory │
│ ○ Remove inventory │
│ │
│ Quantity: [5] │
│ │
│ ┌─────────────────────────────┐ │
│ │ Calculation Preview: │ │
│ ├─────────────────────────────┤ │
│ │ Current stock: 55 │ │
│ │ Adding: +5 │ │
│ │ ═══════════════════════ │ │
│ │ New stock: 60 ✓ │ │
│ └─────────────────────────────┘ │
│ │
│ Reason: │
│ ● Recount correction │
│ ○ Found missing stock │
│ ○ System error │
│ ○ Transfer from storage │
│ ○ Other: [___________] │
│ │
│ [Cancel] [Confirm Adjustment] │
└─────────────────────────────────┘
Adjustment Reasons:
- Recount correction
- Found missing stock
- System error
- Transfer from storage
- Other (free text)
5.3 Error Prevention
Cannot Remove More Than Available
Quantity to dump: [100]
┌─────────────────────────────────┐
│ Calculation Preview: │
├─────────────────────────────────┤
│ Current stock: 60 │
│ Removing: -100 │
│ ═══════════════════════ │
│ New stock: -40 ❌ │
│ │
│ ⚠️ Cannot remove more than │
│ available! │
│ Max: 60 portions │
└─────────────────────────────────┘
[Confirm] ← DISABLED
Large Adjustment Warning
If dumping > 15 portions OR value > 500 TSH:
┌─────────────────────────────────┐
│ ⚠️ Confirm Large Waste │
├─────────────────────────────────┤
│ Dumping: 50 portions │
│ Value: 2,000 TSH │
│ Reason: End of day dump │
│ │
│ This is a significant loss. │
│ Please confirm. │
│ │
│ [Cancel] [Yes, Dump] │
└─────────────────────────────────┘
5.4 Permission Recommendations
| Action | Kitchen Staff | Manager |
|---|---|---|
| Prep New Batch | ✓ | ✓ |
| Dump/Waste | ✓ | ✓ |
| Manual Adjust | ✗ | ✓ |
6. Counter App Interface
6.1 Smart Sides Flow (Core UX)
The counter app uses a unified, intelligent flow that eliminates the need for staff to choose between "combos" or "custom builds". Staff simply taps what the customer orders, and the system handles combo detection automatically.
Design Philosophy
| Old Approach | New Smart Sides Approach |
|---|---|
| Staff chooses: Combo OR Custom OR Standalone | One natural flow for everything |
| Must memorize which combos exist | System suggests and auto-applies |
| Three different paths to learn | "Tap main, pick sides, done" |
| Easy to pick wrong option | Cannot go wrong |
The Flow
Step 1: Staff sees main dishes only
No combo clutter. Just the base items organized by category.
┌─────────────────────────────────────────────────┐
│ JikoXpress Counter │
├─────────────────────────────────────────────────┤
│ │
│ MAIN DISHES │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐│
│ │ Ugali │ │ Wali │ │ Chapati │ │ Chips ││
│ │ 300 │ │ 250 │ │ 200 │ │ 400 ││
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘│
│ │
│ DRINKS │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Chai │ │ Juice │ │ Soda │ │
│ │ 100 │ │ 200 │ │ 150 │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │
└─────────────────────────────────────────────────┘
Step 2: Staff taps main dish → Smart Sides popup appears
System shows all possible sides, with combo savings highlighted.
┌─────────────────────────────────────────────────┐
│ Add Sides to Ugali? [x] │
├─────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Maharage +300 💰 SAVE 100 │ │
│ │ Combo available! │ │
│ └─────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Nyama Choma +500 💰 SAVE 150 │ │
│ │ Combo available! │ │
│ └─────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Kachumbari +150 🔥 Popular │ │
│ │ 47 orders │ │
│ └─────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Sukuma Wiki +200 │ │
│ └─────────────────────────────────────────────┘ │
│ │
│ [+ Custom Side] [Skip → No Sides] │
│ │
└─────────────────────────────────────────────────┘
Step 3: System auto-detects and applies combo pricing
┌─────────────────────────────────────────────────┐
│ Cart │
├─────────────────────────────────────────────────┤
│ │
│ Ugali Maharage x1 600 │
│ ├─ Ugali │
│ └─ Maharage 💰 Saved 100! │
│ │
│ ───────────────────────────────────────────── │
│ Subtotal: 600 │
│ │
│ [+ Add More] [Checkout →] │
│ │
└─────────────────────────────────────────────────┘
6.2 Smart Sides Popup Logic
What Appears in the Popup
The popup shows sides from three sources, in priority order:
| Priority | Source | Badge | Description |
|---|---|---|---|
| 1 | Existing Combos | 💰 SAVE X | Sides that complete a predefined combo |
| 2 | Customer Behavior | 🔥 Popular | Frequently ordered together (learned) |
| 3 | Manual Pairings | (none) | Admin-defined suggestions |
Popup Display Rules
- Show combo sides first (sorted by savings amount)
- Show popular/learned sides second (sorted by order count)
- Show manual pairings last
- Maximum 6-8 sides visible (scroll for more)
- Always show "Custom Side" and "Skip" options
6.3 Cart Intelligence
The system automatically determines the best pricing based on what's selected.
Scenario 1: Side Completes a Combo
Staff picks: Ugali → Maharage
Cart shows:
┌─────────────────────────────────────────────────┐
│ Ugali Maharage x1 600 │
│ 💰 Saved 100! │
└─────────────────────────────────────────────────┘
Internally tracked as: MENU_SCHEDULE order
Revenue allocation: Proportional to components
Scenario 2: No Sides Selected (Skip)
Staff picks: Ugali → Skip
Cart shows:
┌─────────────────────────────────────────────────┐
│ Ugali x1 300 │
└─────────────────────────────────────────────────┘
Internally tracked as: STANDALONE order
Revenue: Full price to Ugali
Scenario 3: Sides Don't Match Any Combo
Staff picks: Ugali → Kachumbari (no combo exists)
Cart shows:
┌─────────────────────────────────────────────────┐
│ Ugali x1 300 │
│ Kachumbari x1 150 │
└─────────────────────────────────────────────────┘
Internally tracked as: CUSTOM_BUILD order
Revenue: Full standalone prices
Scenario 4: Multiple Mains
Customer: "Ugali na Wali, zote na maharage"
Staff flow:
1. Tap Ugali → Pick Maharage → Cart: "Ugali Maharage x1 - 600"
2. Tap Wali → Pick Maharage → Cart adds: "Wali Maharage x1 - 650"
Cart shows:
┌─────────────────────────────────────────────────┐
│ Ugali Maharage x1 600 │
│ Wali Maharage x1 650 │
│ ───────────────────────────────────────────── │
│ Subtotal: 1,250 │
└─────────────────────────────────────────────────┘
Each main is a separate cart item with its own sides flow.
Scenario 5: Drinks as Main
Customer: "Chai mbili tu"
Staff flow:
1. Tap Chai → Skip (or popup shows no relevant sides)
2. Adjust quantity to 2
Cart shows:
┌─────────────────────────────────────────────────┐
│ Chai x2 200 │
└─────────────────────────────────────────────────┘
Drinks are treated as main dishes. They can have their own
sides popup (e.g., Chai + Mandazi combo) or be skipped.
6.4 Quantity Handling
Quantity applies to the entire combo, not individual components.
Customer: "Ugali maharage mbili"
Cart shows:
┌─────────────────────────────────────────────────┐
│ Ugali Maharage x2 1,200 │
│ 💰 Saved 200! │
└─────────────────────────────────────────────────┘
This means:
- 2x Ugali portions
- 2x Maharage portions
- Combo price × 2
6.5 Cart & Checkout
┌─────────────────────────────────────────────────┐
│ Current Order │
├─────────────────────────────────────────────────┤
│ │
│ Ugali Maharage x1 600 │
│ 💰 Saved 100 │
│ │
│ Wali Nyama x1 800 │
│ 💰 Saved 150 │
│ │
│ Chai x2 200 │
│ │
│ ───────────────────────────────────────────── │
│ Subtotal: 1,600 │
│ Discount (10%): -160 │
│ ═════════════════════════════════════════════ │
│ Total: 1,440 │
│ │
│ Total Saved from Combos: 250 │
│ │
│ [💰 Apply Discount] │
│ │
│ Payment Method: │
│ [💵 Cash] [📱 Mobile Money] │
│ │
│ [✅ Complete Order] │
│ │
└─────────────────────────────────────────────────┘
6.6 Staff Training Summary
The entire training can be reduced to:
"Tap the main dish customer wants.
Pick sides from the popup if they want any.
If they want it plain, tap Skip.
System handles the rest."
No need to memorize combos. No need to choose between different order types. Just tap what you hear.
7. Customer App Flow
7.1 Time-Based Menu Display
Customer app shows only menus currently visible based on time.
8:00 AM Customer View:
┌─────────────────────────────────────────────────┐
│ 🌅 Breakfast Menu │
├─────────────────────────────────────────────────┤
│ │
│ COMBO DEALS │
│ ┌─────────────────────────────────────────────┐ │
│ │ 🍳 Mandazi + Chai 200 TSH │ │
│ │ 💰 Save 20! │ │
│ ├─────────────────────────────────────────────┤ │
│ │ 🍚 Ugali + Maharage 350 TSH │ │
│ │ 💰 Save 50! │ │
│ └─────────────────────────────────────────────┘ │
│ │
│ INDIVIDUAL ITEMS │
│ ┌─────────────────────────────────────────────┐ │
│ │ Mandazi 120 TSH │ │
│ │ Chai 100 TSH │ │
│ │ Ugali 200 TSH │ │
│ └─────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────┘
7.2 Standalone Item Solution
Problem: Customer wants just Mandazi, but only "Mandazi + Chai" combo exists.
Solution: Create both combo AND individual menu schedules.
Breakfast Menus (6:00 - 10:00):
1. "Mandazi + Chai" (combo) = 200 TSH
2. "Mandazi" (individual) = 120 TSH
3. "Chai" (individual) = 100 TSH
Customer can choose:
- Combo (save 20 TSH)
- Just Mandazi
- Just Chai
8. Reports & Analytics
8.1 Daily Sales Report
═══════════════════════════════════════════════════════
DAILY SALES REPORT - January 15, 2025
═══════════════════════════════════════════════════════
SUMMARY:
───────────────────────────────────────────────────────
Total Orders: 45
Gross Sales: 50,000 TSH
Discounts Given: -3,500 TSH (7%)
Net Sales: 46,500 TSH
Total Food Cost: 18,600 TSH
Gross Profit: 27,900 TSH
Profit Margin: 60%
DISCOUNT BREAKDOWN:
───────────────────────────────────────────────────────
Manager Override: 2,000 TSH
Promo Codes: 1,000 TSH
Staff Meals: 500 TSH
PAYMENT METHODS:
───────────────────────────────────────────────────────
Cash: 30,000 TSH (64%)
Mobile Money: 16,500 TSH (36%)
8.2 Item Sales Report
═══════════════════════════════════════════════════════
ITEM SALES REPORT - January 15, 2025
═══════════════════════════════════════════════════════
Item Qty Revenue Cost Profit Margin
───────────────────────────────────────────────────────────────
Ugali 45 11,571 4,500 7,071 61.1%
Maharage 52 13,943 10,400 3,543 25.4%
Wali 35 8,750 3,500 5,250 60.0%
Nyama 28 15,736 8,400 7,336 46.6%
Chai 30 3,000 600 2,400 80.0%
───────────────────────────────────────────────────────────────
TOTAL 190 53,000 27,400 25,600 48.3%
TOP PERFORMERS (by profit):
1. Nyama: 7,336 TSH (28 sold)
2. Ugali: 7,071 TSH (45 sold) ⭐ High volume
3. Wali: 5,250 TSH (35 sold)
ATTENTION NEEDED:
1. Maharage: 25.4% margin ⚠️
- High volume but lowest margin
- Consider: raise prices or reduce prep cost
8.3 Item Deep Dive Report
═══════════════════════════════════════════════════════
UGALI - DETAILED P&L REPORT
═══════════════════════════════════════════════════════
Quantity Sold: 45 portions
REVENUE BREAKDOWN:
───────────────────────────────────────────────────────
From Menu "Ugali + Maharage Special":
25 orders × 257.14 allocated = 6,428.50
From Menu "Ugali + Nyama Special":
15 orders × 240.00 allocated = 3,600.00
From Standalone:
5 orders × 300.00 full price = 1,500.00
From Custom Builds:
(various allocations) = 42.50
───────────────────────────────────────────────────────
Total Revenue: 11,571.00
Total Cost: 4,500.00 (45 × 100)
═══════════════════════════════════════════════════════
Gross Profit: 7,071.00
Profit Margin: 61.1%
Average Revenue per Portion: 257.13
Cost per Portion: 100.00
Average Profit per Portion: 157.13
8.4 Waste Report
═══════════════════════════════════════════════════════
WASTE REPORT - January 15, 2025
═══════════════════════════════════════════════════════
BY COMPONENT:
───────────────────────────────────────────────────────
Beans: 5 portions (200 TSH cost)
• Spoiled: 3 portions
• Poor quality: 2 portions
Ugali: 12 portions (1,200 TSH cost)
• End of day: 12 portions
Rice: 3 portions (150 TSH cost)
• Dropped: 3 portions
───────────────────────────────────────────────────────
TOTAL WASTE: 20 portions
TOTAL COST: 1,550 TSH
% OF FOOD COST: 2.8%
WASTE BY REASON:
───────────────────────────────────────────────────────
End of day dump: 12 portions (60%)
Spoiled: 3 portions (15%)
Poor quality: 2 portions (10%)
Dropped: 3 portions (15%)
8.5 Prep Report
═══════════════════════════════════════════════════════
PREP REPORT - January 15, 2025
═══════════════════════════════════════════════════════
TIME STAFF ITEM QTY COST
───────────────────────────────────────────────────────
08:00 Chef John Beans 50 2,000
08:30 Chef John Ugali 30 1,500
09:00 Chef Mary Rice 40 1,600
12:00 Chef John Beans 25 1,000
14:30 Chef Mary Ugali 20 1,000
───────────────────────────────────────────────────────
TOTAL PREP COST: 7,100
BY CHEF:
Chef John: 105 portions 4,500 TSH
Chef Mary: 60 portions 2,600 TSH
8.6 Menu Engineering Matrix
═══════════════════════════════════════════════════════
MENU ENGINEERING MATRIX
═══════════════════════════════════════════════════════
│ High Profit │ Low Profit
──────────────┼──────────────────────┼─────────────────
High Volume │ ⭐ STARS │ 🐴 WORKHORSES
│ Nyama, Ugali │ Maharage
│ → Promote heavily │ → Fix pricing
──────────────┼──────────────────────┼─────────────────
Low Volume │ 🔮 PUZZLES │ 🐕 DOGS
│ Wali │ (none currently)
│ → Test promotions │ → Consider removing
──────────────┴──────────────────────┴─────────────────
RECOMMENDATIONS:
───────────────────────────────────────────────────────
⭐ Nyama: Keep promoting - high margin, growing volume
⭐ Ugali: Maintain quality - consistent performer
🐴 Maharage: Increase price to 450 or reduce prep cost
🔮 Wali: Run "Wali Specials" to boost volume
8.7 Audit Trail
═══════════════════════════════════════════════════════
ADJUSTMENT AUDIT - January 15, 2025
═══════════════════════════════════════════════════════
TIME STAFF ACTION ITEM QTY REASON
───────────────────────────────────────────────────────
08:00 Chef John PREP Beans +50 Morning prep
08:30 Chef John PREP Ugali +30 Morning prep
14:30 Chef Mary DUMP Ugali -3 Poor quality
16:00 Chef Mary DUMP Beans -2 Spoiled
20:00 Manager ADJUST Beans -2 Recount
20:30 Chef John DUMP Ugali -12 End of day
───────────────────────────────────────────────────────
LARGE ADJUSTMENTS (>15 portions or >500 TSH):
• 20:30 - Ugali dump: 12 portions (1,200 TSH)
Approved by: Manager
Reason: End of day - remaining portions
9. Image Management
9.1 Strategy
| Entity | Image Requirement |
|---|---|
| Dish | REQUIRED - all dishes must have image |
| Menu Schedule | OPTIONAL - custom hero image |
| Fallback | Use component images if no menu image |
9.2 Image Sizes
Original: 1200 × 1200 (storage)
Large: 800 × 800 (desktop detail view)
Medium: 600 × 600 (mobile, listings)
Thumbnail: 200 × 200 (cart, small displays)
9.3 Image Requirements
Format: JPEG or PNG (WebP preferred)
Max Size: 5MB
Min Size: 400 × 400
Quality: 80-85% compression
10. Data Models Summary
10.1 Complete Entity Diagram
┌─────────────────┐
│ Dish │
├─────────────────┤
│ id │
│ name │
│ prepCost │
│ sellingPrice │
│ currentInventory│
│ canSellStandalone│
│ imageUrl │
│ active │
└────────┬────────┘
│
│ components
▼
┌─────────────────┐
│ MenuSchedule │
├─────────────────┤
│ id │
│ name │
│ category │
│ session │
│ scheduleType │
│ menuType │
│ sellingPrice │
│ visibleFrom │
│ visibleUntil │
│ activeDays │
│ active │
└────────┬────────┘
│
│ combo (nullable)
▼
┌─────────────────┐
│ DishPairing │◄─────────────────────────────────┐
├─────────────────┤ │
│ id │ │
│ mainDish │──► Dish │
│ sideDish │──► Dish │
│ combo │──► MenuSchedule (nullable) │
│ source │ (COMBO, BEHAVIOR, MANUAL) │
│ orderCount │ │
│ savings │ │
│ displayOrder │ │
│ active │ │
└─────────────────┘ │
│
┌─────────────────┐ ┌─────────────────┐ │
│ OrderItem │◄───────│ Order │ │
├─────────────────┤ ├─────────────────┤ │
│ id │ │ id │ │
│ dish │ │ orderNumber │ │
│ menuSchedule │ │ orderType │ │
│ quantity │ │ subtotal │ │
│ sourceType │ │ discountType │ │
│ priceType │ │ discountAmount │ │
│ allocatedRevenue│ │ total │ │
│ prepCost │ │ paymentMethod │ │
│ profit │ │ status │ │
└─────────────────┘ │ createdBy │ │
│ createdAt │ │
└─────────────────┘ │
│
┌─────────────────┐ ┌─────────────────┐ │
│ StockAdjustment │ │ PairingAnalytics│───────┘
├─────────────────┤ ├─────────────────┤
│ id │ │ id │
│ dish │ │ mainDish │
│ adjustmentType │ │ sideDish │
│ quantity │ │ orderCount │
│ reason │ │ lastOrdered │
│ reasonCategory │ │ periodStart │
│ costImpact │ │ periodEnd │
│ adjustedBy │ └─────────────────┘
│ adjustedAt │
│ previousStock │
│ newStock │
└─────────────────┘
10.2 Enums
| Enum | Values |
|---|---|
| MenuCategory | MAIN_FOOD, DRINKS, SNACKS, DESSERTS |
| FoodSession | BREAKFAST, LUNCH, DINNER, ALL_DAY |
| ScheduleType | ONE_TIME, DAILY, WEEKLY, PERMANENT |
| MenuType | COMBO, INDIVIDUAL_ITEM |
Orders & Sales
| Enum | Values |
|---|---|
| OrderType | MENU_SCHEDULE, CUSTOM_BUILD, STANDALONE |
| SourceType | MENU_SCHEDULE, CUSTOM_BUILD, STANDALONE |
| PriceType | ALLOCATED, FULL_PRICE |
| OrderStatus | PENDING, COMPLETED, CANCELLED |
| PaymentMethod | CASH, MOBILE_MONEY |
Discounts
| Enum | Values |
|---|---|
| DiscountType | PERCENTAGE, FIXED_AMOUNT, PROMO_CODE, MANAGER_OVERRIDE, STAFF_MEAL, ROUNDING |
Inventory & Adjustments
| Enum | Values |
|---|---|
| AdjustmentType | PREP, DUMP, MANUAL_ADD, MANUAL_REMOVE |
| WasteReason | SPOILED_EXPIRED, POOR_QUALITY, OVERCOOKED, DROPPED_ACCIDENT, END_OF_DAY, OTHER |
| AdjustmentReason | RECOUNT_CORRECTION, FOUND_MISSING, SYSTEM_ERROR, TRANSFER_FROM_STORAGE, OTHER |
Dish Pairings
| Enum | Values |
|---|---|
| PairingSource | COMBO, BEHAVIOR, MANUAL |
11. Key System Benefits
For Restaurant Owners
- Real-time inventory - always know what's available
- Item-level profitability - see profit per dish
- Waste tracking - understand where money is lost
- Staff accountability - track who does what
- Menu optimization - identify stars and dogs
- Behavior insights - see what customers actually want
- Combo suggestions - system recommends new combos based on data
For Kitchen Staff
- Simple prep tracking - one tap to log
- Easy waste logging - categorized reasons
- Live inventory - no surprise stockouts
- Clear audit trail - protect from blame
For Counter Staff
- One simple flow - tap main, pick sides, done
- No memorization - system suggests combos
- Auto pricing - combos detected automatically
- Flexible discounts - handle any situation
- Clear totals - live calculation preview
- Multiple payment - cash and mobile money
For Customers
- Faster service - staff doesn't fumble with options
- Always get best price - combos auto-applied
- Consistent experience - same flow every time
For System
- Component-level truth - single source for inventory
- Proportional allocation - fair revenue distribution
- Complete audit - every action logged
- Learning engine - improves suggestions over time
- Scalable - handles growth from 10 to 10,000 orders
12. Implementation Checklist
Phase 1: Core Setup
- Dish entity with inventory
- Menu Schedule entity
- Category and Session enums
- Basic CRUD operations
Phase 2: Smart Sides
- Dish Pairing entity
- Auto-generate pairings from combos
- Pairing display priority logic
- Smart Sides popup component
Phase 3: Orders
- Order entity
- OrderItem with source tracking
- Cart intelligence (combo detection)
- Revenue allocation service
- Discount application
Phase 4: Inventory
- Stock adjustment system
- Prep tracking
- Waste management
- Audit trail
Phase 5: Counter App
- Main dishes display
- Smart Sides popup
- Cart with combo badges
- Checkout flow
- Discount UI
Phase 6: Behavior Learning
- Order pattern tracking
- Pairing analysis service
- Admin insights dashboard
- Combo suggestions
Phase 7: Reports
- Daily sales summary
- Item profitability
- Waste reports
- Prep reports
- Menu engineering
- Pairing performance
Phase 8: Customer App
Document Version: 1.0
Last Updated: December 2024
Author: JikoXpress Development Team
JikoXpress Pro: Checkout & Order Management Architecture
Document Information
| Property | Value |
|---|---|
| Version | 2.1 |
| Status | Draft |
| Created | December 2025 |
| Updated | January 2026 |
| Purpose | Development Guide & Requirements Reference |
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:
| Principle | Description |
|---|---|
| Single Source of Truth | All channels (POS, Kiosk, App, WhatsApp, etc.) create the same Order entity. Kitchen sees one unified queue regardless of where orders originate. |
| Progressive Feature Unlocking | 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. |
| Zero-Config Defaults | Works immediately after signup. Set your menu, start taking orders. No complex setup required. Customize only what you need. |
| Device-Agnostic Operations | Register any device (phone, tablet, dedicated terminal) as POS, Kiosk, or KDS. Configure each device's role and capabilities independently. |
| Channel-Flexible Menu | One menu, configurable per channel. Set different prices for delivery, hide items from kiosks, restrict items by fulfillment type. |
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
| Tier | Target User | Key Features | Limits |
|---|---|---|---|
| STARTER | Home chefs, vendors | Mobile app, basic menu, mobile money | 20 items, 100 orders/mo |
| GROWING | Small restaurants | + POS, Kiosk, printers, card payments | 1,000 orders/mo, 3 staff |
| PROFESSIONAL | Full restaurants | + KDS, stations, tabs, drive-through | Unlimited orders, 15 staff |
| ENTERPRISE | Chains, franchises | + Multi-location, API, white-label | Unlimited everything |
Key Differentiators
-
East Africa First - Built for M-Pesa, Tigo Pesa, Airtel Money. Designed for local restaurant workflows and trust models.
-
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.
-
Offline-Capable - POS works offline, queues orders, syncs when connected. Critical for areas with unreliable internet.
-
Multi-Channel by Default - Not an add-on. Every kitchen can receive orders from POS, app, WhatsApp, and kiosks simultaneously from day one.
-
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 & 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 & small vendors"
Price: Free or minimal fee
Features Included:
Limits:
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 & 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 & lounges, hotel restaurants
ENTERPRISE Plan
Tagline: "For chains & 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 & 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 > 80 (approaching 100 limit)
- Menu items > 15 (approaching 20 limit)
- Customer requested card payment
- Multiple login attempts (wants staff accounts)
GROWING → PROFESSIONAL Triggers:
- Orders this month > 800 (approaching 1,000 limit)
- Staff accounts maxed at 3
- Searched for: tabs, dine-in, stations, KDS
- Average prep time > 15 minutes
PROFESSIONAL → ENTERPRISE Triggers:
- Asked about second location
- Searched for: multi-location, franchise, API
- Orders this month > 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:
- Staff enters items into cart
- Identifies customer (optional)
- Selects fulfillment type (dine-in with table number)
- Chooses payment timing: Pay Now or Pay Later (Tab)
- Processes payment or opens tab
- 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:
- Customer browses menu on touchscreen
- Adds items to cart with modifications
- Proceeds to checkout
- Selects payment method
- Completes payment (or receives cash payment slip)
- Receives printed stub with order number
- 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:
| Aspect | Web (No App) | App |
|---|---|---|
| Login | Not required | Optional |
| Cart | Browser session | Persistent |
| Payment | USSD, Cash | USSD, Cash, Wallet |
| Order History | Not available | Available |
| Push Notifications | Not available | Available |
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)
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:
- Customer enters lane
- Places order at order point (speaker or screen)
- Proceeds to payment window
- Proceeds to pickup window
- 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
| Aspect | POS | Kiosk | Table QR | App | Drive-Through | |
|---|---|---|---|---|---|---|
| Operator | Staff | Customer | Customer | Customer | Customer | Staff/Screen |
| Cart Storage | Memory | Session | Session/App | Server | Conversation | Memory |
| Customer ID | Optional | Anonymous | Anonymous | Required | Phone | Optional |
| Pay Later (Tab) | Yes | No | No | No | No | No |
| Fulfillment | All | Dine-in, Pickup | Dine-in | All | Delivery, Pickup | Drive-Through |
| Speed Priority | Critical | High | Normal | Normal | Normal | Critical |
| Time SLA | Normal | Normal | Normal | Normal | Normal | Critical |
| Min Plan | GROWING | GROWING | STARTER | All | GROWING | PROFESSIONAL |
2.3 POS Service Modes
POS devices can operate in different service modes depending on the restaurant setup:
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 & 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:
| Status | Description | Kitchen Visible | Payment Status |
|---|---|---|---|
| CREATED | Order recorded but not yet submitted | No | Not started |
| PENDING_PAYMENT | Awaiting async payment confirmation | Depends on config | In progress |
| CONFIRMED | Payment complete or tab opened | Yes | Paid or Deferred |
| PREPARING | Kitchen actively working on order | Yes | N/A |
| READY | Order complete, waiting for pickup | Yes | N/A |
| COMPLETED | Customer received order | No | N/A |
| CANCELLED | Order cancelled before completion | No | Refunded if paid |
3.3 Payment Status (Separate from Order Status)
Orders track payment independently:
| Payment Status | Description |
|---|---|
| UNPAID | No payment received (tab scenario) |
| PENDING | Async payment initiated, awaiting confirmation |
| PARTIAL | Some payment received (future feature) |
| PAID | Full payment received |
| REFUNDED | Payment returned to customer |
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
| Type | Description | Queue Identifier | Handoff Point |
|---|---|---|---|
| DINE_IN | Customer eats at restaurant | Table Number | Table |
| PICKUP | Customer collects order | Order Number | Counter |
| DELIVERY | Order delivered to customer | Address | Door |
| DRIVE_THROUGH | Vehicle-based pickup | Lane + Order # | Window |
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
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
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 > 2 minutes
- Payment processing > 1 minute
- Pickup wait > 3 minutes
- Lane backup detected
Part 5: Checkout Flow
5.1 Universal Checkout Principles
Regardless of channel, checkout always involves:
- Identify Items - What is being ordered
- Identify Customer - Who is ordering (optional for some channels)
- Identify Fulfillment - How order will be fulfilled
- Calculate Totals - Items + taxes + fees - discounts
- Select Payment - How customer will pay
- Process Payment - Execute payment or defer
- Create/Confirm Order - Finalize and notify kitchen
5.2 Default Flow (Zero Configuration)
If a kitchen sets nothing, this is what happens:
Default Configuration:
fulfillmentTypes: [PICKUP]
paymentTiming: ON_PAYMENT_COMPLETE
orderRouting: DISPLAY_ONLY
kitchenNotification: DISPLAY
printOnConfirm: true
customerStub: true
tabsEnabled: false
Default Experience:
- Kitchen signs up
- Sets their menu
- Immediately can take orders via mobile app
- 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:
| Status | Description |
|---|---|
| ACTIVE | Checkout in progress |
| COMPLETED | Payment successful, order created |
| EXPIRED | Session timed out (15 min default) |
| CANCELLED | User or system cancelled |
Part 6: Payment Architecture
6.1 Payment Method Categories
Immediate Settlement
| Method | Description | Channels |
|---|---|---|
| Cash | Physical currency | POS, Kiosk |
| Card Swipe | Card terminal | POS, Kiosk |
| Kitchen Wallet | Kitchen-issued balance | POS |
| App Wallet | Platform wallet | POS (QR), App |
Asynchronous Settlement
| Method | Description | Channels |
|---|---|---|
| Mobile Money (USSD) | Customer confirms on phone | All |
| QR Scan (App Wallet) | POS displays QR | POS |
| Payment Link | Customer clicks link |
Deferred Settlement
| Method | Description | Channels |
|---|---|---|
| Pay Later (Tab) | Opens tab, pay before leaving | POS only |
6.2 Payment Method by Plan
| Method | STARTER | GROWING | PROFESSIONAL | ENTERPRISE |
|---|---|---|---|---|
| Mobile Money (USSD) | ✓ | ✓ | ✓ | ✓ |
| Cash | - | ✓ | ✓ | ✓ |
| Card | - | ✓ | ✓ | ✓ |
| Kitchen Wallet | - | ✓ | ✓ | ✓ |
| App Wallet | ✓ | ✓ | ✓ | ✓ |
| Pay Later (Tab) | - | - | ✓ | ✓ |
| Custom Methods | - | - | ✓ | ✓ |
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
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
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:
| Preset | Stations Created |
|---|---|
| Fast Food | Hot Line, Cold Line, Drinks |
| Full Restaurant | Hot Line, Cold Line, Bar, Bakery, Expeditor |
| Cafe / Coffee Shop | Barista, Kitchen, Display |
| Pizza Place | Pizza Station, Grill, Salads, Bar |
| No Stations | All orders on single screen |
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?
| Setting | Description | Use Case |
|---|---|---|
| ON_ORDER_CREATED | Before payment | Trusted dine-in |
| ON_PAYMENT_COMPLETE | After payment | Kiosk, delivery |
| MANUAL | Staff triggers | Special events |
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
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
| Print Type | When | Where | Purpose |
|---|---|---|---|
| Kitchen Ticket | Order to kitchen | Kitchen printer | What to prepare |
| Customer Receipt | Payment completed | POS printer | Proof of purchase |
| Bill/Check | Customer requests | POS printer | Amount due |
| Order Stub | Kiosk order | Kiosk printer | Order number |
| Void Notice | Item voided | Kitchen printer | Cancel notification |
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)
orderRouting: NONE
kitchenNotification: NONE
sendToKitchen: immediate (same person)
customerStub: false
customerDisplay: false
tabsEnabled: false
Fast Food Preset
orderRouting: DIRECT_TO_STATIONS
kitchenNotification: DISPLAY
sendToKitchen: ON_PAYMENT_COMPLETE
customerStub: true
customerDisplay: true
tabsEnabled: false
Casual Dining Preset
orderRouting: DIRECT_TO_STATIONS
kitchenNotification: PRINTER
sendToKitchen: ON_PAYMENT_COMPLETE
customerStub: optional
customerDisplay: false
tabsEnabled: true
Fine Dining Preset
orderRouting: EXPEDITOR_CONTROLLED
kitchenNotification: BOTH
sendToKitchen: ON_ORDER_CONFIRMED
customerStub: false
customerDisplay: false
tabsEnabled: true (default for dine-in)
Drive-Through Preset
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
orderRouting: DISPLAY_ONLY
kitchenNotification: DISPLAY
sendToKitchen: ON_PAYMENT_COMPLETE
customerStub: true
customerDisplay: single screen
tabsEnabled: false
Part 11: Device Management
11.1 Device Types & Roles
Each app type knows its responsibilities:
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
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:
| Device | Fulfillment Types | Service Modes | Location |
|---|---|---|---|
| POS-Counter-1 | Dine-In, Pickup | Counter | Main counter |
| POS-Counter-2 | Pickup only | Counter | Takeaway window |
| POS-DriveThru | Drive-Through only | Counter | DT Window |
| Tablet-Waiter-1 | Dine-In only | Table Service | Floor |
| Kiosk-Entrance | Dine-In, Pickup | N/A | Entrance |
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 & Pricing
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
| Scenario | Configuration |
|---|---|
| Alcohol only on POS | Beer: visible on POS only, hidden on Kiosk/App |
| Delivery markup | All items: +1000 on App/WhatsApp channels |
| Soup not for drive-through | Soup: fulfillment DRIVE_THROUGH = unavailable |
| Happy hour pricing | Beer: different price on POS during specific hours |
| Dine-in exclusive | Special dish: fulfillment = DINE_IN only |
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 & Features
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:
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:
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
deliverySettings:
enabledProviders: [JIKOXPRESS_DASHERS, BOLT_FOOD]
preferredProvider: JIKOXPRESS_DASHERS
fallbackProvider: BOLT_FOOD
autoAssign: true | false
15.3 Order Delivery Properties
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: < 200ms
- Kitchen notification: < 500ms from trigger
- Print job creation: < 200ms
- KDS refresh: Real-time (< 2s)
- Drive-through order entry: < 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
| Term | Definition |
|---|---|
| Tab | Container for unpaid orders at a dine-in table |
| Stub | Small printed slip with order number |
| KDS | Kitchen Display System - digital order screens |
| Expeditor | Senior staff controlling order flow |
| Station | Specific preparation area in kitchen |
| Bump | Mark order complete on KDS |
| Fire | Send order to kitchen for preparation |
| Void | Cancel an item from an order |
| Kitchen Wallet | Prepaid balance issued by kitchen |
| App Wallet | Platform-wide customer wallet |
| Lane | Drive-through vehicle queue |
| Device | Registered hardware (POS, Kiosk, KDS, Tablet, Display) |
| Channel | Source of order (POS, Kiosk, App, WhatsApp, etc.) |
| Fulfillment | How order is delivered (Dine-in, Pickup, Delivery, Drive-through) |
| Service Mode | POS operation style (Counter Service, Table Service) |
| Delivery Status | Shipping progress for delivery orders |
| Account | Owner entity that can have multiple kitchens |
| Customer Facing Screen | Display at POS showing cart to customer |
| Menu Board | Digital display showing menu items and prices |
| Order Status Display | Screen showing preparing/ready orders |
| Queue Display | Screen showing "Now Serving" numbers |
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
| Decision | Choice | Rationale |
|---|---|---|
| Credit system (Kwa Deni) | Removed | Complexity vs V1 scope |
| Tab creation | Auto on first pay-later | Less friction for staff |
| Partial payments | Defer to V2 | Complexity vs actual need |
| Drive-through | Channel + Fulfillment | Unified model, same order entity |
| Feature unlocking | Subscription-based | Clear value tiers, simple UX |
| Default config | Zero-config works | Reduce onboarding friction |
| Print architecture | Client pull | Local printer support, offline |
| Order number | Daily reset | Easier for kitchen communication |
| Platform scale | One codebase all tiers | Same APIs, feature flags gate access |
| Device registration | Email + code + kitchen select | Secure, supports multi-kitchen accounts |
| One device one kitchen | Must logout to switch | Simplifies operations, prevents confusion |
| Station assignment | Pre-defined in menu setup | Automatic routing, no manual selection |
| Menu channel settings | Per-channel visibility/pricing | Flexibility for delivery markup, restrictions |
| Delivery status | Separate from order status | Two parallel tracking (kitchen vs shipping) |
| POS service modes | Counter vs Table service | Same device, different workflows |
Document History
| Version | Date | Changes |
|---|---|---|
| 1.0 | December 2025 | Initial document |
| 2.0 | January 2026 | Removed Kwa Deni, added Drive-Through, added Progressive Feature Unlocking, added Subscription Tiers, added Default Configuration, noted Multi-Provider Delivery |
| 2.1 | January 2026 | 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 |
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
| Type | Description |
|---|---|
IMMEDIATE |
Pay now, right at this terminal |
SLIP |
Generate slip, customer goes to cashier |
TAB |
Pay later, dine-in rounds |
Session Statuses
| Status | Description |
|---|---|
PENDING_PAYMENT |
Waiting for payment — USSD webhook or cashier confirmation |
CONFIRMED |
Payment done, order created |
EXPIRED |
Slip timed out, inventory released |
CANCELLED |
Manually cancelled, inventory released |
FAILED |
Payment failed, inventory released |
Payment Methods
| Method | Description |
|---|---|
CASH |
Physical money |
MOBILE_MONEY |
USSD — M-Pesa, Tigo, Airtel |
CARD |
Visa, Mastercard |
PLATFORM_WALLET |
JikoXpress app wallet |
KITCHEN_WALLET |
Kitchen issued prepaid balance |
KITCHEN_CHANNEL |
Kitchen configured channel — Lipa Voda, HaloPesa etc |
Instructions
| Level | Field | Use Case |
|---|---|---|
| Session | orderInstructions |
One note for whole order — POS, Kiosk, Dine-in |
| Item | itemInstructions |
Per item note — App, mixed kitchen orders |
Both can be used together. Session instruction goes to kitchen as a general note. Item instruction travels with that specific item.
Channel & Fulfillment Matrix
| Channel | DINE_IN | PICKUP | DELIVERY | DRIVE_THROUGH |
|---|---|---|---|---|
POS |
✅ | ✅ | ❌ | ✅ |
KIOSK |
✅ | ✅ | ❌ | ❌ |
TABLE_QR |
✅ | ❌ | ❌ | ❌ |
APP |
❌ | ✅ | ✅ | ❌ |
WHATSAPP |
❌ | ✅ | ✅ | ❌ |
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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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:
| Field | Resolved From |
|---|---|
staffId |
Authenticated staff session token |
accountId |
Authenticated JikoXpress user token |
| Kitchen (POS/Kiosk) | Staff session — staff belongs to a kitchen |
| Kitchen (App direct) | Passed in request |
| Kitchen (App cart) | Derived from cart items grouped by kitchen |
Payment Split Model
All payments are a list. Single payment = list of one. Amounts must sum to session total.
{
"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
}
]
}
kitchenCustomerIdrequired only forKITCHEN_WALLET
kitchenPaymentMethodIdrequired only forKITCHEN_CHANNEL
Scenarios
1. POS — Pay Now, Cash
Staff takes order at counter. Customer pays cash immediately.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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 newKitchenBillsEntityautomatically
Nopayments— customer pays at end
7. POS — Tab, Round 2 (Existing Bill)
Same table orders more. Cashier picks existing open bill, adds new round.
{
"sessionType": "TAB",
"channel": "POS",
"fulfillmentType": "DINE_IN",
"tableNumber": "05",
"billId": "existing-bill-uuid",
"items": [
{"menuId": "uuid", "quantity": 2, "itemInstructions": null}
]
}
billIdlinks 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.
{
"sessionType": "SLIP",
"channel": "KIOSK",
"fulfillmentType": "PICKUP",
"items": [
{"menuId": "uuid", "quantity": 2, "itemInstructions": null},
{"menuId": "uuid", "quantity": 1, "itemInstructions": null}
]
}
kitchenIdderived 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.
{
"sessionType": "IMMEDIATE",
"channel": "KIOSK",
"fulfillmentType": "PICKUP",
"items": [
{"menuId": "uuid", "quantity": 1, "itemInstructions": null}
],
"payments": [
{
"paymentMethod": "MOBILE_MONEY",
"amount": 5000
}
]
}
Session stays
PENDING_PAYMENTuntil USSD webhook confirms
10. Table QR — Pay on Phone
Customer scans QR at table, orders, pays via USSD on their own phone.
{
"sessionType": "IMMEDIATE",
"channel": "TABLE_QR",
"fulfillmentType": "DINE_IN",
"tableNumber": "05",
"items": [
{"menuId": "uuid", "quantity": 1, "itemInstructions": null}
],
"payments": [
{
"paymentMethod": "MOBILE_MONEY",
"amount": 5000
}
]
}
kitchenIdembedded 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.
{
"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.
{
"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
}
]
}
accountIdfrom auth token
kitchenIdderived from cart items — one session created per kitchen
fromCart: true— noitemsneeded in request
13. App — Direct Buy, No Cart
App user buys directly from a kitchen without going through cart.
{
"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
kitchenIdrequired since not derived from cart
14. WhatsApp — Delivery
Customer orders via WhatsApp chatbot. Not a JikoXpress user — identified by phone number only.
{
"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
}
]
}
kitchenIdfrom chatbot — each kitchen has their own WhatsApp number
customerPhoneidentifies customer — no JikoXpress account needed
NoaccountId— 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.
{
"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.
{
"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
{
"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
{
"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
{
"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