JikoXpress Pro: Checkout & Order Management Architecture

JikoXpress Pro: Checkout & Order Management Architecture

Document Information

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)WhatsApp, Table QR, Drive-Through), flexible payment methods, configurable kitchen operations, and comprehensive printing workflows.

The architecture prioritizesis built on three core principles:

1. Single Source of Truth - All channels create Orders through a singleunified sourcemodel
of
2. Progressive truthFeature whileUnlocking maintaining- flexibilityFrom forhome kitchen to enterprise chain on one platform
3. 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 tochains finewith dining,drive-through from paper tickets to digital kitchen displays.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:

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

Limits:

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

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

GROWING Plan

Tagline: "For busy kitchens ready to scale"

Price: Mid-tier monthly fee

Features Included:

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

Limits:

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

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

PROFESSIONAL Plan

Tagline: "Full-featured restaurant management"

Price: Higher-tier monthly fee

Features Included:

• Everything in GROWING
• Kitchen stations
• KDS (Kitchen Display System)
• Drive-through support
• Tabs (pay-later for dine-in)
• Table management
• Up to 15 staff accounts
• Roles & 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

1.2.1 Channel Overview

JikoXpress Pro supports sixseven distinct sales channels, each with unique characteristics and requirements.characteristics.

POS (Point of Sale)

The primary channel for counter staff and waiters.

Characteristics:

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

Availability: GROWING plan and above

Typical Flow:

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

Kiosk

Self-service terminals for customer-driven ordering.

Characteristics:

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

Availability: GROWING plan and above

Typical Flow:

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

Table QR

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

Characteristics:

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

TypicalAvailability: Flow:

• Customer sits at table, scans QR code
• QR contains: kitchen ID + table number
• System detects: Has app? → Open in app : Open web menu
• Customer browses menu on their phone
• Adds items to cart with modifications
• Proceeds to checkout
• Table number pre-filledplan (from1 QR)
table),
• Selects payment method:
  • USSD: Receives prompt, confirms payment
  • Cash: Order sent, customer pays at counter
  • App Wallet: If logged into app, can use wallet
• Order confirmed, sent to kitchen
• Food delivered to tableGROWING+ (staff knows table number)

QR Code Content:

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

Web vs App Experience:

Table QR Advantages:

• No app download required (web fallback)
• Reduces staff workload (customer self-orders)
• Table number automatic (no errors)
• Customer orders at their own pace
• Can add more items easily (scan again or keep session)

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

TypicalAvailability: Flow:All plans (customer-facing)

• User browses menu in app
• Adds items to persistent cart
• Selects fulfillment (delivery address or pickup location)
• Proceeds to checkout
• Pays using saved payment method or new method
• Receives confirmation and real-time status updates

WhatsApp

Conversational ordering via chatbot integration.

Characteristics:

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

Availability: GROWING plan and above

Drive-Through

Vehicle-based ordering and pickup.

Characteristics:

• ConfirmationDesigned sentfor viaspeed WhatsApp- messagetime SLA is critical
• Lane-based queue management
• Speaker/mic or digital menu board ordering
• Payment and pickup at windows
• Vehicle tracking by order number

Availability: PROFESSIONAL plan and above

Typical Flow:

1. Customer messagesenters kitchen's WhatsApp numberlane
2. ChatbotPlaces guidesorder throughat menuorder selectionpoint (speaker or screen)
3. ConfirmsProceeds orderto detailspayment window
4. SendsProceeds paymentto optionspickup (USSD prompt or payment link)
5. Customer completes payment externallywindow
6. Receives confirmation message with order detailsand 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)

1.2.2 Channel Comparison Matrix

*Wallet only available if customer has app and is logged in

Part 2:3: Order & Tab Architecture

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

2.3.2 Order Lifecycle

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

State Definitions:

2.3.3 Payment Status (Separate from Order Status)

Orders track payment independently:

This separation allows:

• Kitchen to prepare food while payment is UNPAID (tab scenario)
• Order to be CONFIRMED but payment PENDING (async payment)
• Clear tracking for end-of-day reconciliation

2.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 Creation:

• Auto-created when first "Pay Later" order placed for a table
• One open tab per table per day
• Identified by: Kitchen + Table Number + Date + Status

Tab Rules:

• Customer can add more orders to open tab (new orders, not modifying existing)
• 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 (not modifying single order):Tab:

• Kitchen already received and is preparing original order
• New items create new kitchen tickets (clear for kitchen staff)
• Each order has clean, independent lifecycle
• Item-level status tracking remains accurate
• Simplifies kitchen display and ticket management

2.3.5 KwaFulfillment Deni (Credit/Debt System)Types

A controlled feature allowing trusted customers to take food on credit and pay later - days or weeks after consumption.

Important: This is NOT the same as Tab (pay later same day). Kwa Deni is actual debt that extends beyond the restaurant visit.

2.5.1 Feature Characteristics

Availability:

• POS channel ONLY
• NOT available on Kiosk, App, or WhatsApp
• Hidden by default - not visible in standard POS interface
• Must be explicitly enabled by kitchen admin
• Requires special permission for staff to use

Security Controls:

• Kitchen-level setting to enable/disable entirely
• Staff-level permission required (not all staff can offer credit)
• Customer must be registered (no anonymous credit)
• Credit limit per customer (optional)
• Manager approval option for amounts above threshold

2.5.2 Kwa Deni vs Tab Comparison

2.5.3

---

Kwa

Part Deni4: 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

Creating Debt:

1.LANE_ENTRY Customer→ ordersORDER_POINT food→ PAYMENT_WINDOW → PICKUP_WINDOW → EXIT
     ↓            ↓              ↓               ↓
  (registereddetected)  customer required)
2. Staff completes (order entry
3. At payment, staff selects "Kwa Deni" optioncreated) (if permitted)
4. System checks:
   - Is feature enabled for this kitchen?
   - Does staff have credit permission?
   - Is customer registered?
   - Is customer within credit limit?payment)    (if limits configured)
   - Does amount require manager approval?
5. If manager approval needed:
   - Manager enters PIN or approves
6. Order created with:
   - paymentStatus: CREDIT
   - Linked to customer's debt account
7. Kitchen receives order normally
8. Customer leaves without paying
9. Debt recorded against customerhanded)

Paying Off Debt:

1. Customer returns to pay (or staff initiates)
2. Staff looks up customer's debt balance
3. System shows:
   - Total outstanding debt
   - Individual unpaid orders (optional detail)
   - Oldest debt date
4. Customer can pay:
   - Full amount (clears all debt)
   - Partial amount (reduces debt balance)
   - Specific orders (if itemized payment enabled)
5. Payment processed
6. Debt balance updated
7. Receipt shows: Payment toward credit balance

2.5.4 Debt Tracking

Customer Debt Account:

• Total outstanding balance
• List of unpaid orders
• Payment history
• Credit limit (if set)
• Last payment date
• Oldest unpaid order date

Debt Order Properties:

• Standard order properties
• paymentStatus: CREDIT
• debtCreatedAt: When debt was created
• debtDueDate: Optional due date
• debtApprovedBy: Staff/manager who approved

Debt Payment Properties:

• Amount paid
• Payment method
• Applied to which orders (or general balance)
• Remaining balance after payment

2.5.53 Configuration Options

Kitchen Level:

Kwa DeniDrive-Through Settings:
├──
  enabled: false (defaultdefault)
  numberOfLanes: 1-4
  
  orderPointType:
    - hiddenSPEAKER_MIC        entirely)# ├──Staff requireManagerApproval:takes true/falseorder ├──via approvalThreshold:speaker
    Amount- aboveDIGITAL_MENU_BOARD which# managerCustomer mustself-orders approveon ├──screen
    allowPartialPayment:- true/falseBOTH               ├──# showInPOS:Screen falsewith (evenstaff ifbackup
  
  enabled,windowConfiguration:
    can- beSINGLE_WINDOW      hidden# fromPay mainand UI)pickup ├──at defaultCreditLimit:same 0window
    (no- limit)SEPARATE_WINDOWS   or# amountPayment └──window, debtAgingAlertDays:then 30pickup (alertwindow
  
  forvehicleTracking:
    old- debt)ORDER_NUMBER       # Customer given number, called at window
    - MANUAL             # Staff tracks position manually
    - TIMER_BASED        # System estimates based on avg times

Staff

4.4 Level:

Drive-Through Order Properties

Staff Credit Permission:
├── canOfferCredit: falseOrder (default)when ├──fulfillment maxCreditAmount:= MaximumDRIVE_THROUGH):
  singlelaneNumber: transaction1-4
  └──vehicleDescription: requiresApprovalAbove:"Red AmountToyota" requiring(optional)
  managerorderPointTimestamp: overridewhen order was taken
  paymentWindowTimestamp: when payment completed
  pickupWindowTimestamp: when order handed off

Customer

4.5 Level:

Customer Credit Settings:
├── creditEnabled: true/false (can this customer use credit)
├── creditLimit: Maximum outstanding balance allowed
├── currentBalance: Current debt amount
└── creditStatus: GOOD_STANDING | SUSPENDED | BLOCKED

2.5.6 Business Rules

Who Can Receive Credit:

• Must be registered customer with verified identity
• Kitchen admin can whitelist specific customers
• Optional: Require minimum purchase history
• Optional: Credit application/approval process

Credit Limits:

• Global default limit (kitchen setting)
• Per-customer override (higherTicket for trusted, lower for new)
• Can be zero (unlimited) for corporate accounts

When Credit is Blocked:

• Customer exceeds credit limit
• Customer has debt older than X days
• Customer status set to SUSPENDED or BLOCKED
• Staff attempts without permission

Partial Payments:

• If enabled, customer can pay any amount toward balance
• Payment applied to oldest debt first (FIFO)
• Or customer/staff can specify which orders to pay

2.5.7 Reporting & Alerts

Debt Reports:

• Total outstanding debt (all customers)
• Debt by customer
• Aging report (0-30 days, 31-60 days, 60+ days)
• Debt created today/this week/this month
• Payments received toward debt

Alerts:

• Customer approaching credit limit
• Customer exceeding credit limit
• Debt aging past threshold
• Large credit transaction (above threshold)

2.5.8 UI Considerations

Hidden by Default:

• Kwa Deni option NOT visible in standard payment screen
• Access via: Settings menu, long-press, or special navigation
• Prevents accidental use
• Prevents customer seeing and requesting it

When Visible:

• Only shown after admin enables AND staff has permission
• Clear visual distinction from regular payment
• Warning/confirmation before proceeding
• Shows customer's current balance before adding more

2.5.9 Receipt for Credit Transaction

================================
        JIKOXPRESSORDER KITCHEN#47
     ================================Lane Receipt2 #:| R-20241229-0052DRIVE-THROUGH
   Date:12:34 29-Dec-2024PM 14:30| Customer: John Doe03-Jan-2026
--------------------------------
ITEMS:>> HOT LINE <<

1x Burger
   12,000- 1xNo onions
   - Extra cheese

2x Fries
   5,000- Large

--------------------------------
TOTAL:⚡ 17,000
================================
PAYMENT: CREDIT (Kwa Deni)
Approved by: Manager Jane

Previous Balance:      25,000
This Order:            17,000DRIVE-THROUGH -------------------------------- NEWSPEED BALANCE DUE:       42,000
================================
   Payment due upon request
================================

2.5.10 Receipt for Debt Payment

================================
       JIKOXPRESS KITCHEN
================================
Receipt #: R-20241229-0067
Date: 29-Dec-2024 16:45
Customer: John Doe
--------------------------------
PAYMENT TOWARD CREDIT BALANCE

Previous Balance:      42,000
Payment (Cash):       -20,000
--------------------------------
REMAINING BALANCE:     22,000
================================
      Thank you!PRIORITY
================================

2.4.6 OrderDrive-Through vs Tab vs Kwa Deni Decision FlowMetrics

Which channel?
├── POS: How will customer pay?
│   ├── Pay Now: Create Order, process payment immediately
│   ├── Pay Later (Tab): Find/create Tab, Order linked
Due to Tabthe │critical │nature └──of Customerspeed MUSTin paydrive-through:
before
Tracked leavingMetrics:
│

└──
Average Kwatime Deniper vehicle

Time at each station (Credit): 
│       ├── Check: Feature enabled? Staff permitted? Customer registered?
│       ├── If all yes: Create Order with paymentStatus: CREDIT
│       └── Customer can leave, pays another day
│
├── Kiosk: Create Order, require payment (no Tab, no Kwa Deni)
│   └── Cash option: Kitchen timing configurable
│
├── Table QR: Create Order, require payment (no Tab, no Kwa Deni)
│   ├── USSD/Wallet: Processorder, payment, confirmpickup)
order
Orders │per └──hour Cashper option:lane
Kitchen
Peak timinghour configurableanalysis
│
├──
Alerts:
App:

Create
Order Order,taking require> immediate2 paymentminutes
│
Payment └──processing WhatsApp:> Create1 Order,minute
require
Pickup immediatewait payment> 

Part 3:5: Checkout Flow

3.5.1 Universal Checkout Principles

Regardless of channel, checkout always involves:

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

5.2 Default Flow (Zero Configuration)

If a kitchen sets nothing, this is what happens:

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

Default Experience:

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

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

5.3 Channel-Specific Checkout Flows

POS Checkout (Pay Now)

1. Staff finalizes cart
2. System creates checkout session
3.2 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 process
• Protection against abandoned checkouts
• Support for async payment flows
• Prevention of race conditions

Session Properties:

• Expires after configured time (e.g., 15 minutes)
• Contains cart snapshot at checkout initiation
• Links to Order once created
• Tracks payment attempts and status

Session States:

3.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 and shows available payment methods
5. Staff selects payment method
6. System processes payment
7. Order created with status CONFIRMED, paymentStatus PAID
8. Kitchen notified (based on configuration)
9. Receipt printed

POS Checkout (Pay Later / Tab)

1. Staff finalizes cart
2. Staff selects "Pay Later" and enters table number
3. System finds existing open Tab for table OR creates new Tab
4. Order created with status CONFIRMED, paymentStatus UNPAID
5. Order linked to Tab
6. Kitchen notified immediately
7. Customer stub printed (optional)
8. Tab remains open for additional orders

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

Kiosk Checkout

1. Customer finalizes cart on screen
2. System creates checkout session
3. Customer selects fulfillment (dine-in table or pickup)
4. System shows available payment methods (QR, USSD, Cash, Card)
5. Customer selects payment method:
   - QR: Display QR code, wait for app scan confirmation
   - USSD: Customer enters phone, receives prompt, confirms
   - Cash: Print "pay at counter" slip, staff confirms manually
   - Card: Process via terminal integration
6. On payment confirmation:
   - Order created with status based on kitchen config
   - Kitchen notified (based on configuration)
   - Order stub printed for customer

App Checkout

1. User reviews cart in app
2. User initiates checkout
3. System creates checkout session
4. User selects/confirms delivery address or pickup
5. System calculates totals including delivery fee if applicable
6. User selects payment method (Wallet, USSD, saved methods)
7. User confirms payment
8. On payment confirmation:
   - Order created with status CONFIRMED
   - Kitchen notified
   - Push notification sent to user
   - User sees order tracking screen

WhatsApp Checkout

1. Chatbot summarizes order and total
2. Chatbot asks for fulfillment preference (delivery/pickup)
3. If delivery: Chatbot collects/confirms address
4. Chatbot presents payment options:
   - USSD: Sends prompt to customer's phone
   - Payment Link: Sends clickable payment link
5. Customer completes payment externally
6. Webhook receives payment confirmation
7. Order created with status CONFIRMED
8. Chatbot sends confirmation message with order details
9. Kitchen notified

Table QR Checkout (Web)

1. Customer scans QR code at table
2. Web menu opens in browser (no app needed)
3. Customer browses and adds items to cart
4. Customer taps checkout
5. System creates checkout session
6. Table number pre-filled from QR data
7. Customer selects payment method:
   - USSD: Enter phone number, receive prompt, confirm
   - Cash: Select "Pay at Counter"
8. For USSD:
   - Payment initiated
   - Wait for confirmation
   - Order confirmed, sent to kitchen
   - Customer sees confirmation with order number
9. For Cash:
   - Order created with paymentStatus PENDING_CASH
   - Kitchen notified (based on config: before or after cash confirmed)
   - Customer shown: "Please pay [amount] at counter"
   - Staff confirms cash received
   - Order fully confirmed
10. Food delivered to table (staff knows table from order)

Table QR Checkout (App)

1. Customer scans QR code at table
2. Deep link opens app (if installed)
3. Table number passed to app session
4. Customer browses menu in app
5. Adds items to cart (app cart, persistent if logged in)
6. Customer taps checkout
7. Table number pre-filled from QR
8. Customer selects payment method:
   - App Wallet (if logged in and has balance)
   - USSD
   - Cash (pay at counter)
9. Payment processed or cash selected
10. Order confirmed, sent to kitchen
11. Push notification when ready (if logged in)
12. Food delivered to table

3.4 Checkout Session API Concept

Create Session:

Input:
  - items (menuId, quantity, modifiers, notes)
  - channel (POS, KIOSK, APP, WHATSAPP)
  - customerId (optional)
  - fulfillmentType (DINE_IN, PICKUP, DELIVERY)
  - tableNumber (for dine-in)
  - deliveryAddress (for delivery)

Output:
  - sessionId
  - summary (items, subtotal, taxes, fees, total)
  - availablePaymentMethods (filtered by channel and kitchen config)
  - expiresAt

Process Payment:

Input:
  - paymentMethod
  - paymentDetails (method-specific data)
  - payLater (boolean, POS only)
  - tabId (if adding to existing tab)

Output:
  - status (COMPLETED, PENDING, DEFERRED)
  - orderId
  - tabId (if tab created or used)
  - paymentInstructions (for async: QR data, USSD prompt, link)

Part 4:6: Payment Architecture

4.6.1 Payment Method Categories

Immediate Settlement

Payment completes instantly within the transaction.

Asynchronous Settlement

Payment initiated but confirmation arrives later via callback/webhook.

Deferred Settlement

No payment now, to be collected later.

6.2 Payment Method by Plan

4.2 Payment Method Configuration

Each kitchen configures which payment methods are available and for which channels.

Configuration Properties:

• Method type and name
• Enabled/disabled status
• Which channels can use this method
• Whether manual confirmation is required
• Method-specific configuration (Lipa number, bank details, etc.)

Example Configurations:

Fast Food Restaurant:

• Cash: POS, Kiosk
• Card: POS, Kiosk
• Mobile Money: All channels
• App Wallet: POS (QR), App
• Pay Later: Disabled

Fine Dining Restaurant:

• Cash: POS
• Card: POS
• Kitchen Wallet: POS (for regulars)
• Pay Later: POS (enabled)
• Mobile Money: Disabled

4.6.3 Payment Processing Flow

Immediate Payment Flow

1. Customer/staff selects payment method
2. System validates method is available for channel
3. For Wallet: Check sufficient balance
4. Process payment:
   - Wallet: Deduct balance, record transaction
   - Cash: Mark as received, staff confirms
   - Card: Send to terminal, await response
5. On success: Update payment status to COMPLETED
6. Create payment record
7. Proceed with order confirmation

Async Payment Flow

1. Customer/staff selects async payment method
2. System creates payment record with status PENDING
3. System generates payment instructions:
   - QR: Generate QR code data
   - USSD: Initiate USSD push to customer phone
   - Link: Generate unique payment URL
4. Return instructions to client for display
5. Customer completes payment externally
6. Payment provider sends webhook/callback
7. System validates callback authenticity
8. Update payment status to COMPLETED
9. Update order status to CONFIRMED
10. Trigger kitchen notification

Deferred Payment Flow (Tab)

1. Staff selects "Pay Later"
2. System creates/finds Tab for table
3. Order created with paymentStatus UNPAID
4. Order linked to Tab
5. Kitchen proceeds with preparation
6. [Customer adds more orders - repeat steps 2-5]
7. When ready to close:
   - Staff retrieves Tab
   - System calculates total across all orders
   - Staff applies discounts if needed
   - Staff processes payment (any immediate method)
   - Tab status set to CLOSED
   - All linked orders set to paymentStatus PAID

4.4 Kitchen Wallet

A prepaid balance system for loyal customers, managed by the kitchen.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
• Balance visible to POS staff during checkout

Use Cases:

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

4.5 Partial Payments

Current Recommendation: Not supported in V1

Rationale:

• Adds significant complexity to payment tracking
• Edge cases around partial failures
• Reconciliation becomes more difficult
• Rare in actual restaurant operations

Future Consideration:

• Schema should support multiple payment records per order/tab
• UI restricts to single payment method initially
• Can be enabled for POS dine-in scenarios later

4.66.4 Discount Handling

Discounts can be applied at checkout to reduce the total.

Discount Types:

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

Discount Application Points:

• Item level: Discount on specific menu item
• Order level: Discount on order subtotal
• Tab level: Discount on tab total (before final payment)

Staff Discount Limits:Limits (PROFESSIONAL+):

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

Example Discount Flow:

Tab total: 50,000
Staff applies 10% discount (within their 10% limit)
New total: 45,000
Customer pays: 45,000 ✓

Tab total: 50,000
Staff needs 20% discount (exceeds their 10% limit)
System prompts for manager PIN
Manager enters PIN
Discount approved and recorded
New total: 40,000
Customer pays: 40,000 ✓

Part 5:7: Kitchen Operations

5.7.1 Operation Models

Model A: Direct Counter Service (Default for STARTER)

Order Confirmed → Same person prepares → Immediate handoff

RestaurantsNo operatekitchen differently.routing, Theno systemprinters, mustno support multiple models.complexity.

Model A:B: Paper Ticket Kitchen

Traditional model with physical tickets.

Order Confirmed → Print ticket → Hand-carry to kitchen →
Kitchen works from paper
→ Calls out order number

Characteristics:

• Reliable,reliable, no technology dependency in kitchen
• Kitchen staff familiar with paper workflow
• Requires physical ticket transport
• Limited real-time status visibility

Model B:C: Kitchen Display System (KDS)

Modern paperless kitchen.

Order Confirmed → Appears on kitchen screen →
Kitchen marks items done on screen → Customer notified

Characteristics:

• Real-time order visibility
• Item-level status tracking
• No paper waste
• Requires reliable network and hardware

Model C: Hybrid

Kitchen uses both screens and paper.

Order Confirmed → Appears on screen AND prints ticket → ScreenKitchen formarks overview, paper for line cooksdone

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

• Best of both worlds
• Redundancy if one system fails
• Higher operational cost

Model D: Expeditor ControlledHybrid

Expeditor (senior staff) controls kitchen flow.

Order Confirmed → GoesScreen toAND expeditorpaper

Best of both, redundancy if one fails.

Model E: Expeditor Controlled (Fine Dining)

Order Confirmed → Expeditor screen → Expeditor "fires"fires items when ready →
Station receives items in controlled sequence

Characteristics:

• Pacing control for multi-course meals
• Prevents kitchen overwhelm
• Requires trained expeditor
• Best for fine dining

Model E: Direct Counter Service

No kitchen routing needed.meals.

Order Confirmed → Same person prepares and serves →
Immediate handoff to customer

Characteristics:

• Simplest model
• For small operations
• Counter person sees order on POS screen

5.7.2 Kitchen Stations (PROFESSIONAL+)

Larger kitchens have multiple stations, each responsible for certain menu items.stations:

Common Stations:

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

Station Routing:

• Each menu item assigned to a station
• When order confirmed, items grouped by station
• Each station receives only their items
• Supports parallel preparation

Example Order Routing:Example:

Order #47:
├── Burger → Hot Line
├── Caesar Salad → Cold Line
├── Beer → Bar
└── Cheesecake → Cold Line
Hot Line receives: 1x Burger
Cold Line receives: 1x Caesar Salad, 1x Cheesecake
Bar receives: 1x Beer

5.7.3 Kitchen Timing Configuration

Critical Decision: When does kitchen receive the order?

ConfigurationDefault by Channel:

Kitchen can set different timing for different channels:

• POS Dine-in: ON_ORDER_CREATED (trusted customers)
• POS Pickup: ON_PAYMENT_COMPLETE (ensure payment)
• Kiosk: ON_PAYMENT_COMPLETE or configurable
• Table QR: ON_PAYMENT_COMPLETE or configurable (like Kiosk)
• App: ON_PAYMENT_COMPLETE
• WhatsApp: ON_PAYMENT_COMPLETE

Kitchen Operation Settings:
  ├──orderRouting:
    Order Routing Mode
│   ├──- DIRECT_TO_STATIONS
    (items go directly to assigned stations)
│   ├──- EXPEDITOR_CONTROLLED
    (expeditor fires items)
│   ├──- DISPLAY_ONLY
    (no auto-print, screen only)
│   └──- NONE (counter service,service no- kitchendefault)
  
  routing)notificationMethod:
    │
├── Notification Method
│   ├──- DISPLAY (KDSKDS)
    screens)
│   ├──- PRINTER
    (paper tickets)
│   ├──- BOTH
    (screen and paper)
│   └──- NONE (counter service)service │- ├──default)
  
  TimingtimingByChannel:
    by Channel
│   ├── POS Dine-in:pos_dine_in: ON_ORDER_CREATED | ON_PAYMENT_COMPLETE
    │   ├── POS Pickup: ON_ORDER_CREATED |pos_pickup: ON_PAYMENT_COMPLETE
    │   ├── Kiosk:kiosk: ON_PAYMENT_COMPLETE
    | configurable
│   ├── Table QR:table_qr: ON_PAYMENT_COMPLETE
    | configurable
│   ├── App:app: ON_PAYMENT_COMPLETE
    │   └── WhatsApp:whatsapp: ON_PAYMENT_COMPLETE
    │drive_through: ├──ON_PAYMENT_COMPLETE
  
  KioskkioskCashFlow:
    Cash Flow
│   ├──- KITCHEN_FIRST (prepare before paymentcash confirmed)
    │   └──- PAYMENT_FIRST (wait for cash confirmation)- │
└── Table QR Cash Flow
    ├── KITCHEN_FIRST (prepare before payment confirmed)
    └── PAYMENT_FIRST (wait for cash confirmation)default)

┌─────────────────────────────────────────────────────────────┐
│  HOT LINE                                      2:34 PM      │
├─────────────────────────────────────────────────────────────┤
│  #47        │  #48         │  #49         │  #51           │
│  Table 5    │  Pickup      │  Table 2     │  Delivery      │
│  2 min ago  │  5 min ago   │  1 min ago   │  Just now      │
│─────────────│──────────────│──────────────│────────────────│
│  1x Burger  │  2x Wings    │  1x Steak    │  3x Burger     │
│   -no onion │  1x Burger   │  1x Fish     │  2x Wings      │
│  2x Fish    │              │              │  1x Salad      │
│             │              │              │                │
│  [START]    │  [WORKING]   │  [START]     │  [START]       │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                    NOW SERVING                              │
│                                                             │
│     #45      #46                                           │
├─────────────────────────────────────────────────────────────┤
│                    PREPARING                                │
│                                                             │
│     #47      #48      #49      #50      #51                │
└─────────────────────────────────────────────────────────────┘

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

1x Burger
   - No onions
   - Extra cheese

2x Fish & Chips
   - One mild spice

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

================================
      ** ADD TO #47 **
     Table 5 | Dine-in
   12:52 PM | 29-Dec-2024
--------------------------------
>> HOT LINE <<

1x Chicken Wings

--------------------------------
================================

================================
     ** VOID FROM #47 **
     Table 5
--------------------------------
>> HOT LINE <<

VOID: 1x Burger

Reason: Customer changed mind
Approved: Manager Jane
================================

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

      TAX ID: 12345678
================================
Receipt #: R-20241229-20260103-0047
Date: 29-Dec-202403-Jan-2026 13:45
Table: 5
Server: John
Cashier: Mary
--------------------------------
ITEMS:
1x Burger              12,000
   Extra cheese         1,500
2x Fish & Chips        30,000
1x Chicken Wings        8,000
1x Caesar Salad         7,500
2x Beer                 8,000
--------------------------------
Subtotal:              67,00043,500
Discount (10%):        -6,700
--------------------------------4,350
VAT (18%):              10,8547,047
--------------------------------
TOTAL:                 71,15446,197
================================
PAYMENT:
CashMobile 75,000Money           Change:46,197
3,846Ref: MP12345678
================================
      Thank you!
Please come again

  ** WiFi: kitchen2025 **
================================

================================
       JIKOXPRESS KITCHEN
================================
       TABLE 5 - BILL
   29-Dec-2024 13:30
--------------------------------
1x Burger              12,000
   Extra cheese         1,500
2x Fish & Chips        30,000
1x Chicken Wings        8,000
1x Caesar Salad         7,500
2x Beer                 8,000
--------------------------------
Subtotal:              67,000
VAT (18%):             12,060
--------------------------------
TOTAL DUE:             79,060
================================
   Please pay at counter

   This is not a receipt
================================

================================
      ORDER #47
================================
   Your order is being
      prepared!
--------------------------------
1x Burger
2x Fish & Chips

Pickup at: COUNTER A
Wait time: ~10 mins
--------------------------------
Show this stub when your
number is called

#47
================================

ON PAYMENT_COMPLETE for KIOSK:
  → Print kitchen ticket
  → Print customer stub
  → Notify KDS

ON PAYMENT_COMPLETE for POS:
  → Print kitchen ticket
  → Print receipt
  → Notify KDS

ON ORDER_CONFIRMED for POS (dine-in):
  → Print kitchen ticket (payment comes later)

ON TAB_CLOSED for POS:
  → Print receipt

ON BILL_REQUESTED:
  → Print bill

PENDING → CLAIMED → PRINTED
              ↓
           FAILED

1. Order confirmed
2. Backend creates PrintJob (status: PENDING)
3. POS app polls: GET /print-jobs?status=PENDING
4. POS app claims job: POST /print-jobs/{id}/claimjob
5. POS app formatsprints content for local printerlocally
6. POS app printsmarks 7. POS app updates: POST /print-jobs/{id}/complete

{
  "type": "KITCHEN_TICKET",
  "orderNumber": 47,
  "orderType": "DINE_IN",
  "tableNumber": "5",
  "station": "Hot Line",
  "timestamp": "2024-12-29T12:34:00",
  "server": "John",
  "isAddition": false,
  "isVoid": false,
  "items": [
    {
      "name": "Burger",
      "quantity": 1,
      "modifiers": ["No onions", "Extra cheese"],
      "notes": null
    },
    {
      "name": "Fish & Chips",
      "quantity": 2,
      "modifiers": ["One mild spice"],
      "notes": null
    }
  ]
}