JikoXpress Pro: Checkout & Order Management Architecture

Document Information

Property	Value
Version	2.0
Status	Draft
Created	December 2025
Updated	January 2026
Purpose	Development Guide & Requirements Reference

Executive Summary

This document defines the complete architecture for JikoXpress Pro's checkout and order management system. The system supports multiple sales channels (POS, Kiosk, Mobile App, WhatsApp, Table QR, Drive-Through), flexible payment methods, configurable kitchen operations, and comprehensive printing workflows.

The architecture is built on three core principles:

Single Source of Truth - All channels create Orders through a unified model
Progressive Feature Unlocking - From home kitchen to enterprise chain on one platform
Zero-Config Defaults - Works immediately, customize as needed

JikoXpress Pro serves diverse restaurant operation models - from a home chef with a mobile phone to multi-location fast food chains with drive-through lanes.

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

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	WhatsApp

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:

Common Stations:

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

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: Data Model Overview

11.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)

Order Item

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

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)

11.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]

11.3 Entity Relationships

Kitchen
├── 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

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
└── generates → Receipt

Part 12: Delivery Integration (Future)

12.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)

12.2 Kitchen Configuration

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

12.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 13: Operational Scenarios

13.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.

13.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

13.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

13.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)

13.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 14: Non-Functional Requirements

14.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

14.2 Reliability

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

14.3 Scalability

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

14.4 Security

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

Part 15: API Structure Overview

15.1 Checkout APIs

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

15.2 Order APIs

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

15.3 Kitchen APIs

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

15.4 Payment APIs

Get payment status
Confirm manual payment
Handle webhooks
Request refund

15.5 Print APIs

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

15.6 Subscription APIs

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

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

Appendix B: Configuration Checklist

STARTER Setup

GROWING Setup (+ STARTER)

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)

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

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

End of Document