JikoXpress Pro: Checkout & Order Management Architecture

Document Information

Property	Value
Version	1.0
Status	Draft
Created	December 2025
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), flexible payment methods, configurable kitchen operations, and comprehensive printing workflows.

The architecture prioritizes a single source of truth while maintaining flexibility for diverse restaurant operation models - from fast food to fine dining, from paper tickets to digital kitchen displays.

Part 1: Sales Channels

1.1 Channel Overview

JikoXpress Pro supports ~~five~~six distinct sales channels, each with unique characteristics and requirements.

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

Typical Flow:

Staff enters items into cart (local/memory storage)
Identifies customer (optional - lookup or quick create)
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 physically present
Anonymous or optional login
Prints order stub for customer

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 for counter)
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

Session-based cart (browser) or linked to app session

Payment: USSD, Cash (pay at counter), App Wallet (if logged in)

Dine-in only

Typical 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-filled (from QR)

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 table (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:

Aspect	Web (No App)	App
Login	Not required	Optional
Cart	Browser session	Persistent
Payment	USSD, Cash	USSD, Cash, Wallet
Order History	Not available	Available
Reorder	Not available	Available
Push Notifications	Not available	Available

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

Typical Flow:

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
Confirmation sent via WhatsApp message

Typical Flow:

Customer messages kitchen's WhatsApp number
Chatbot guides through menu selection
Confirms order details
Sends payment options (USSD prompt or payment link)
Customer completes payment externally
Receives confirmation message with order details

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

1.2 Channel Comparison Matrix

Aspect	POS	Kiosk	Table QR	App	WhatsApp
Operator	Staff	Customer	Customer	Customer	Customer
Cart Storage	Memory/Local	Session	Session/App	Server-side	Conversation
Customer Identity	Optional/Lookup	Anonymous/Login	Anonymous/Login	Required	Phone Number
Pay Later ~~Support~~(Tab)	Yes	No	No	No	No
Kwa Deni (Credit)	Yes (~~Tab)~~hidden)	No	No	No	No
Fulfillment Options	~~Dine-in~~All	Dine-in, Pickup	Dine-in only	All	Delivery, Pickup
Speed Priority	Critical	High	Normal	Normal	Normal
Payment Methods	All	Limited	USSD, Cash, Wallet*	App-supported	USSD, Link
Requires Download	N/A	N/A	No (web fallback)	Yes	No

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

Part 2: Order & Tab Architecture

2.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.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, ready for kitchen	Yes	Paid or Deferred
PREPARING	Kitchen actively working on order	Yes	N/A
READY	Order complete, waiting for pickup/delivery	Yes	N/A
COMPLETED	Customer received order	No	N/A
CANCELLED	Order cancelled before completion	No	Refunded if paid

2.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
CREDIT	Taken on credit - Kwa Deni (debt owed)
REFUNDED	Payment returned to customer

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.4 Tab System (Pay Later)

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

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

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.5 Kwa Deni (Credit/Debt System)

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

Aspect	Tab (Pay Later)	Kwa Deni (Credit/Debt)
Timeline	Same visit	Days/weeks/months
Customer leaves	Must pay first	Can leave without paying
Customer identity	Optional	Required
Default availability	Yes	No (hidden)
Staff permission	All POS staff	Restricted staff only
Partial payment	No	Yes
Risk level	Low	High
Use case	Dine-in convenience	Trusted regulars, corporate accounts

2.5.3 Kwa Deni Flow

Creating Debt:

1. Customer orders food (registered customer required)
2. Staff completes order entry
3. At payment, staff selects "Kwa Deni" option (if permitted)
4. System checks:
   - Is feature enabled for this kitchen?
   - Does staff have credit permission?
   - Is customer registered?
   - Is customer within credit limit? (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 customer

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.5 Configuration Options

Kitchen Level:

Kwa Deni Settings:
├── enabled: false (default - hidden entirely)
├── requireManagerApproval: true/false
├── approvalThreshold: Amount above which manager must approve
├── allowPartialPayment: true/false
├── showInPOS: false (even if enabled, can be hidden from main UI)
├── defaultCreditLimit: 0 (no limit) or amount
└── debtAgingAlertDays: 30 (alert for old debt)

Staff Level:

Staff Credit Permission:
├── canOfferCredit: false (default)
├── maxCreditAmount: Maximum single transaction
└── requiresApprovalAbove: Amount requiring manager override

Customer 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 (higher 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

================================
       JIKOXPRESS KITCHEN
================================
Receipt #: R-20241229-0052
Date: 29-Dec-2024 14:30
Customer: John Doe
--------------------------------
ITEMS:
1x Burger              12,000
1x Fries                5,000
--------------------------------
TOTAL:                 17,000
================================
PAYMENT: CREDIT (Kwa Deni)
Approved by: Manager Jane

Previous Balance:      25,000
This Order:            17,000
--------------------------------
NEW 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!
================================

2.6 Order vs Tab vs Kwa Deni Decision Flow

Is this POSWhich channel?
├── Yes:POS: How will customer pay?
│   ├── Pay Now: Create Order, process payment immediately
│   ├── Pay Later (Tab): Find/create Tab, Order linked to Tab
│   │   └── Customer MUST pay before leaving
│   └── Kwa Deni (Credit): 
│       ├── Check: Feature enabled? Staff permitted? Customer registered?
│       ├── If all yes: Create Order with paymentStatus: CREDIT
│       └── Customer can leave, pays another day
└│
├── No (Kiosk/App/WhatsApp): 
    └──Kiosk: Create Order, require immediate payment (no Tab, no Kwa Deni)
│   └── Cash option: Kitchen timing configurable
│
├── Table QR: Create Order, require payment (no Tab, no Kwa Deni)
│   ├── USSD/Wallet: Process payment, confirm order
│   └── Cash option: Kitchen timing configurable
│
├── App: Create Order, require immediate payment
│
└── WhatsApp: Create Order, require immediate payment

Part 3: Checkout Flow

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

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

Status	Description
ACTIVE	Checkout in progress
COMPLETED	Payment successful, order created
EXPIRED	Session timed out
CANCELLED	User or system cancelled

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: Payment Architecture

4.1 Payment Method Categories

Immediate Settlement

Payment completes instantly within the transaction.

Method	Description	Channels
Cash	Physical currency, staff confirms receipt	POS, Kiosk
Card Swipe	Card terminal processes immediately	POS, Kiosk
Kitchen Wallet	Deduct from customer's kitchen-issued balance	POS
App Wallet	Deduct from customer's platform wallet	POS (via QR), App

Asynchronous Settlement

Payment initiated but confirmation arrives later via callback/webhook.

Method	Description	Channels
Mobile Money (USSD)	Customer receives prompt, confirms on phone	All
QR Scan (App Wallet)	POS displays QR, customer scans with app	POS
Payment Link	Customer clicks link, pays in browser	WhatsApp
Custom Methods	Lipa Number, bank transfer, etc.	POS

Deferred Settlement

No payment now, to be collected later.

Method	Description	Channels
Pay Later (Tab)	Opens tab, payment collected before leaving	POS only
Kwa Deni (Credit)	Debt recorded, payment collected days/weeks later	POS only (hidden, restricted)

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

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.6 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:

Each staff role has maximum discount percentage allowed
Exceeding limit requires manager approval (PIN or override)
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: Kitchen Operations

5.1 Operation Models

Restaurants operate differently. The system must support multiple models.

Model A: 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, no technology dependency in kitchen
Kitchen staff familiar with paper workflow
Requires physical ticket transport
Limited real-time status visibility

Model B: 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 →
Screen for overview, paper for line cooks

Characteristics:

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

Model D: Expeditor Controlled

Expeditor (senior staff) controls kitchen flow.

Order Confirmed → Goes to expeditor screen →
Expeditor "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.

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

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

Common Stations:

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

Station Routing:

Example Order Routing:

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.3 Kitchen Timing Configuration

Critical Decision: When does kitchen receive the order?

Setting	Description	Use Case
ON_ORDER_CREATED	Before payment	Trusted dine-in, speed priority
ON_PAYMENT_COMPLETE	After payment	Kiosk, delivery, fraud prevention
MANUAL	Staff triggers	Special events, controlled pacing

Configuration 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

Table QR Cash Special Case:

Similar to Kiosk, when Table QR customer selects cash payment:

KITCHEN_FIRST: Order goes to kitchen, customer pays at counter

PAYMENT_FIRST: Order waits until staff confirms cash received

Kitchen configures based on trust model. Since table is known, KITCHEN_FIRST is often acceptable.

Kiosk Cash Special Case:

When kiosk customer selects cash payment:

KITCHEN_FIRST: Order goes to kitchen, customer pays at counter
PAYMENT_FIRST: Order waits until staff confirms cash received

This is kitchen-configurable based on their trust model and layout.

5.4 Kitchen Configuration Summary

Kitchen Operation Settings:
├── 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, no kitchen routing)
│
├── Notification Method
│   ├── DISPLAY (KDS screens)
│   ├── PRINTER (paper tickets)
│   ├── BOTH (screen and paper)
│   └── NONE (counter service)
│
├── Timing by Channel
│   ├── POS Dine-in: ON_ORDER_CREATED | ON_PAYMENT_COMPLETE
│   ├── POS Pickup: ON_ORDER_CREATED | ON_PAYMENT_COMPLETE
│   ├── Kiosk: ON_PAYMENT_COMPLETE | configurable
│   ├── Table QR: ON_PAYMENT_COMPLETE | configurable
│   ├── App: ON_PAYMENT_COMPLETE
│   └── WhatsApp: ON_PAYMENT_COMPLETE
│
├── Kiosk Cash Flow
│   ├── KITCHEN_FIRST (prepare before payment confirmed)
│   └── KioskPAYMENT_FIRST (wait for cash confirmation)
│
└── Table QR Cash Flow
    ├── KITCHEN_FIRST (prepare before payment confirmed)
    └── PAYMENT_FIRST (wait for cash confirmation)

5.5 Kitchen Display System (KDS)

For kitchens using digital displays.

Display Features:

Shows pending orders for station
Color coding by age (green → yellow → red)
Touch to mark item/order complete
Sound alerts for new orders
Filter by station
Priority flagging for rush orders

Display Layout Example:

┌─────────────────────────────────────────────────────────────┐
│  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]       │
└─────────────────────────────────────────────────────────────┘

KDS Configuration:

Which stations to show on this display
Alert thresholds (warning at X minutes, critical at Y minutes)
Sort order (oldest first, priority first)
Sound settings

5.6 Customer Facing Display

Shows customers their order status.

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

Features:

Shows orders ready for pickup
Shows orders being prepared
Optional voice announcement
Updates in real-time

Part 6: Printing Architecture

6.1 Print Types

Print Type	When	Where	Purpose
Kitchen Ticket	Order sent to kitchen	Kitchen printer(s)	Tell kitchen what to prepare
Customer Receipt	Payment completed	POS printer	Proof of purchase
Bill/Check	Customer requests	POS printer	Show amount due before payment
Order Stub	Kiosk/pickup order	Kiosk/counter printer	Customer's order number reference
Void Notice	Item voided	Kitchen printer	Notify kitchen of cancellation

6.2 Kitchen Ticket

Sent to kitchen when order is ready for preparation.

Content:

Order number (large, prominent)
Table number or pickup/delivery indicator
Fulfillment type
Timestamp
Station name (if station-specific)
Items with quantities
Modifiers and special instructions
Server/staff name

Example Kitchen Ticket:

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

1x Burger
   - No onions
   - Extra cheese

2x Fish & Chips
   - One mild spice

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

Station-Specific Printing:

When kitchen has multiple stations:

Items grouped by assigned station
Each station gets ticket with only their items
Same order number on all tickets for coordination

Add-On Ticket (for tab additional orders):

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

1x Chicken Wings

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

Void Ticket:

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

VOID: 1x Burger

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

6.3 Customer Receipt

Printed after payment completion.

Content:

Business information (name, address, tax ID)
Receipt number (for accounting)
Date and time
Staff who processed
Itemized list with prices
Modifiers shown with items
Subtotal
Discounts (shown separately)
Tax breakdown
Total
Payment method and amount
Change given (for cash)
Footer message (customizable)

Example Receipt:

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

      TAX ID: 12345678
================================
Receipt #: R-20241229-0047
Date: 29-Dec-2024 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,000
Discount (10%):        -6,700
--------------------------------
VAT (18%):             10,854
--------------------------------
TOTAL:                 71,154
================================
PAYMENT:
Cash                   75,000
Change:                 3,846
================================
      Thank you!
    Please come again

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

6.4 Bill/Check (Pre-Payment)

Given to customer before payment when they ask "Can I have the bill?"

Content:

Business name
Table identifier
Date/time
Items and prices
Subtotal
Tax
Total due
Note: "This is not a receipt"

Example Bill:

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

6.5 Order Stub

Given to customer at kiosk or counter for pickup reference.

Content:

Order number (large)
Items summary (optional based on config)
Pickup location
Estimated wait time (optional)

Example Stub:

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

6.6 Print Trigger Configuration

Kitchens configure what prints when.

Configurable Triggers:

Event	Possible Actions
ORDER_CONFIRMED	Print kitchen ticket, print customer stub, notify KDS
PAYMENT_COMPLETE	Print kitchen ticket, print receipt, print stub
BILL_REQUESTED	Print bill
ORDER_READY	Notify customer display, send SMS
ITEM_VOIDED	Print void notice

Configuration allows:

Different triggers for different channels
Different triggers for different fulfillment types
Enable/disable specific prints

Example Configurations:

Fast Food:

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

Fine Dining:

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

6.7 Print Job Management

Print Job Lifecycle:

PENDING → CLAIMED → PRINTED
              ↓
           FAILED

Print Job Properties:

Order/Tab reference
Print type (ticket, receipt, stub, etc.)
Target printer or printer type
Content (structured data)
Status
Claimed by (which device)
Timestamps

Print Delivery Models:

Model A: Backend Direct Print

Backend sends directly to network printers
Works for cloud-connected printers
Harder for local USB/Bluetooth printers

Model B: Client Pull (Recommended)

Backend creates print jobs with content
POS/Kiosk app polls for pending jobs
App prints locally
App updates job status
Works with local printers
Supports offline queuing

Client Pull Flow:

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}/claim
5. POS app formats content for local printer
6. POS app prints
7. POS app updates: POST /print-jobs/{id}/complete

6.8 Print Content Structure

Print jobs contain structured data, not pre-formatted text. Client renders based on printer capabilities.

Example Kitchen Ticket Content:

{
  "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
    }
  ]
}

Client app uses kitchen's print template settings to render this appropriately for their printer.

6.9 Print Template Configuration

Each kitchen can customize print appearance.

Template Settings:

Header text (business name, address)
Footer text (thank you message, WiFi password)
Show/hide logo
Paper width (58mm or 80mm)
Font size preferences
Content options (show prices on kitchen ticket, etc.)

Part 7: Numbering Systems

7.1 Order Number

Purpose: Kitchen identification, customer reference, display screens

Format: Simple integer, resets daily

Example: #47

Properties:

Sequential within kitchen within day
Resets to 1 each day
Used on kitchen tickets, stubs, display screens
Easy to call out verbally

Generation:

On order creation
Per kitchen, per date sequence
Must handle concurrent orders (proper locking)

7.2 Receipt Number

Purpose: Accounting, tax compliance, audit trail

Format: Prefix-Date-Sequence

Example: R-20241229-0047 or JKX-20241229-0047

Properties:

Never resets (continuous or daily with date prefix)
Generated only when payment completes
One tab with multiple orders = one receipt
Used for refunds, reports, tax filings

Generation:

On payment completion
Not on order creation (order might be cancelled)
Tab payment generates single receipt for all orders

7.3 Tab Identifier

Purpose: Internal tracking, staff reference

Format: Can use table number as identifier

Display: "Table 5's tab" or "Tab #12"

Properties:

One open tab per table per day
Closed tabs retained for history

7.4 Internal IDs

All entities have UUID primary keys for:

Database relationships
API references
Integration stability

Display numbers (order #, receipt #) are separate from internal IDs.

Part 8: Event-Driven Architecture

8.1 Order Events

The system generates events at key moments. Actions are triggered based on kitchen configuration.

Event Types:

Event	Description
ORDER_CREATED	Order record created
ORDER_CONFIRMED	Order submitted and ready for processing
PAYMENT_INITIATED	Payment process started
PAYMENT_COMPLETE	Payment successful
PAYMENT_FAILED	Payment unsuccessful
SENT_TO_KITCHEN	Kitchen notified of order
ITEM_STARTED	Kitchen started preparing item
ITEM_READY	Item preparation complete
ORDER_READY	All items ready for customer
ORDER_PICKED_UP	Customer received order
ORDER_COMPLETED	Order fully closed
ORDER_CANCELLED	Order cancelled
ITEM_VOIDED	Item removed from order

8.2 Event-Action Mapping

Kitchens configure what happens when events occur.

Configuration Structure:

Event Action:
  - Trigger Event (which event fires this)
  - Action (what to do)
  - Conditions (when to apply)
  - Enabled (on/off)

Example Mappings:

When: PAYMENT_COMPLETE
Conditions: channel = KIOSK
Actions:
  - Print kitchen ticket
  - Print customer stub
  - Notify KDS
  - Update customer display

When: ORDER_READY
Conditions: fulfillment = PICKUP
Actions:
  - Show on customer display
  - Send SMS notification

When: ORDER_CONFIRMED
Conditions: channel = POS, fulfillment = DINE_IN
Actions:
  - Print kitchen ticket (payment comes later for tabs)
  - Notify KDS

8.3 Benefits of Event-Driven Approach

Flexibility: Kitchen customizes workflow without code changes
Decoupling: Core logic separated from notification/printing
Auditability: Event log shows exactly what happened when
Extensibility: New actions added without changing core flow

Part 9: Configuration Presets

9.1 Purpose

Not all kitchens want to configure every setting. Presets provide sensible defaults for common operation types.

9.2 Available Presets

Fast Food Preset

Order Routing: DIRECT_TO_STATIONS
Kitchen Notification: DISPLAY (KDS)
Send to Kitchen: ON_PAYMENT_COMPLETE
Customer Stub: Yes, on payment complete
Customer Display: Enabled
Kiosk Cash Flow: KITCHEN_FIRST
Pay Later (Tab): Disabled

Casual Dining Preset

Order Routing: DIRECT_TO_STATIONS
Kitchen Notification: PRINTER
Send to Kitchen: ON_PAYMENT_COMPLETE
Customer Stub: Optional
Customer Display: Disabled (server delivers)
Kiosk Cash Flow: PAYMENT_FIRST
Pay Later (Tab): Enabled

Fine Dining Preset

Order Routing: EXPEDITOR_CONTROLLED
Kitchen Notification: BOTH (screen + paper)
Send to Kitchen: ON_ORDER_CONFIRMED (trust dine-in)
Customer Stub: Disabled (waiter service)
Customer Display: Disabled
Kiosk: Not used
Pay Later (Tab): Enabled, default for dine-in

Cafe/Coffee Shop Preset

Order Routing: NONE (counter service)
Kitchen Notification: NONE (barista sees POS)
Send to Kitchen: Immediate (same person)
Customer Stub: Simple (name + number)
Customer Display: Optional
Pay Later (Tab): Disabled

Food Truck Preset

Order Routing: DISPLAY_ONLY
Kitchen Notification: DISPLAY (single screen)
Send to Kitchen: ON_PAYMENT_COMPLETE
Customer Stub: Yes
Customer Display: Single screen
Pay Later (Tab): Disabled

9.3 Preset Customization

Kitchen selects preset, then can override any individual setting. Preset just provides starting point.

Part 10: Data Model Overview

This section provides conceptual entity definitions. Not database schemas - just the key entities and their relationships.

10.1 Core Entities

Kitchen

The restaurant or food service establishment.

Has many staff members
Has many menu items
Has configuration settings
Has many orders, tabs, customers

Customer

A person who orders from a kitchen.

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

Tab

A container for dine-in orders that will be paid together.

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

Order

A single order transaction.

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

Order Item

A line item within an order.

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

Payment

A payment transaction.

Can be linked to an order or tab
Has payment method
Has amount
Has status (PENDING, COMPLETED, FAILED, etc.)
Has reference/confirmation code
Records who received (for cash)

Receipt

An immutable record of a completed transaction.

Generated on payment completion
Has unique receipt number
Contains snapshot of items, prices, totals
Records discounts and tax
Records payment method(s)
Cannot be modified (only voided)

Customer Debt Account

Tracks credit/debt (Kwa Deni) for customers.

Belongs to a kitchen and customer
Has total outstanding balance
Has credit limit (optional)
Has status (GOOD_STANDING, SUSPENDED, BLOCKED)
Links to unpaid credit orders
Links to debt payments made

Debt Payment

A payment made toward outstanding credit balance.

Belongs to customer debt account
Has amount paid
Has payment method
Records which orders were paid (optional)
Has remaining balance after payment

Checkout Session

Temporary state during checkout process.

Contains cart snapshot
Has expiration time
Links to created order
Tracks session status

Table QR Code

QR code configuration for a table.

Belongs to a kitchen

Has table number/identifier

Has QR code data (URL with kitchen + table)

Has generated image (for printing)

Enabled/disabled status

Created/updated timestamps

10.2 Configuration Entities

Kitchen Settings

Operational configuration for a kitchen.

Order routing mode
Kitchen notification method
Timing settings by channel
Kiosk cash flow setting
Kwa Deni enabled/disabled (hidden by default)
Kwa Deni approval thresholds

Payment Method

Configured payment options for a kitchen.

Method type and name
Enabled channels
Requires confirmation flag
Method-specific configuration

Kitchen Station

A preparation station within the kitchen.

Name and description
Assigned printer
Display configuration

Kitchen Printer

A printer device for the kitchen.

Name and type (kitchen, receipt, kiosk)
Connection details
Assigned station (for kitchen printers)

Print Template

Customizable print formatting.

Print type (ticket, receipt, stub, bill)
Header and footer text
Content options

Event Action

Configured action triggered by events.

Trigger event
Action type
Conditions (channel, fulfillment)
Enabled status

Staff Discount Limit

Discount permissions by role.

Role
Maximum discount percentage
Requires approval flag

10.3 Entity Relationships

Kitchen
├── has many → Staff
├── has many → Menu Items
├── has many → Customers (Kitchen Wallets)
├── has many → Orders
├── has many → Tabs
├── has many → Payments
├── has many → Receipts
├── has one → Kitchen Settings
├── has many → Payment Methods
├── has many → Kitchen Stations
├── has many → Kitchen Printers
├── has many → Print Templates
└── has many → Event Actions

Tab
├── belongs to → Kitchen
├── has many → Orders
├── has many → Tab Discounts
└── 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 many → Print Jobs
└── generates → Receipt (on payment)

Order Item
├── belongs to → Order
├── references → Menu Item
└── assigned to → Kitchen Station

Payment
├── belongs to → Kitchen
├── belongs to → Order or Tab
└── references → Payment Method

Receipt
├── belongs to → Kitchen
├── belongs to → Order or Tab
├── belongs to → Customer (optional)
└── records → Payment details (snapshot)

Print Job
├── belongs to → Kitchen
├── references → Order or Tab
├── targets → Kitchen Printer
└── uses → Print Template

Part 11: API Structure Overview

This section outlines the conceptual API structure. Not detailed specifications - just the key endpoint groups and their purposes.

11.1 Checkout APIs

Session Management:

Create checkout session from cart
Get session status and details
Process payment for session
Cancel session

Tab Management:

Find or create tab for table
Get tab details with all orders
Apply discount to tab
Remove discount from tab
Get tab summary for payment
Close and pay tab

11.2 Order APIs

Order Operations:

Create order (direct, without tab)
Get order details
Update order status
Cancel order

Order Items:

Add item to unpaid order (rare, usually new order on tab)
Void item from order

11.3 Table QR APIs

QR Code Management:

Generate QR code for table

List all table QR codes for kitchen

Regenerate QR code (if compromised)

Enable/disable QR code

Download QR code image for printing

11.3 Payment APIs

Payment Processing:

Get payment status
Confirm manual payment (cash, custom)
Handle payment webhook callbacks
Request refund

Payment Methods:

List available methods for channel
Get method configuration

11.4 Kwa Deni (Credit/Debt) APIs

Debt Management:

Get customer debt balance
Get customer debt history (orders on credit)
Create credit order (with permission checks)
Record debt payment (full or partial)
Get debt payment history

Debt Administration:

List all customers with outstanding debt
Get aging report
Update customer credit limit
Update customer credit status (suspend, block)
Get debt summary reports

11.4 Kitchen APIs

Kitchen Display:

Get pending orders for station
Update item status
Update order status
Get order details

Order Routing:

Fire order to station (expeditor control)
Bump order (mark complete)

11.5 Print APIs

Print Job Management:

Get pending print jobs for device
Claim print job
Complete print job
Fail print job with reason

Manual Print Triggers:

Reprint kitchen ticket
Print bill for table
Reprint receipt

11.6 Configuration APIs

Kitchen Settings:

Get operation settings
Update operation settings
Apply preset

Payment Method Config:

List payment methods
Enable/disable method
Update method configuration

Print Configuration:

List printers
Configure printer
List templates
Update template

Event Actions:

List configured actions
Create/update action
Enable/disable action

Part 12: Integration Points

12.1 Payment Provider Integration

Mobile Money (USSD):

Initiate payment request
Receive webhook on completion
Query payment status

Card Terminals:

Send payment request
Receive response
Handle terminal errors

Payment Links:

Generate unique payment URL
Track link status
Receive completion webhook

12.2 Notification Integration

SMS:

Order confirmation
Order ready notification
Delivery updates

Push Notifications (App):

Order status updates
Ready for pickup
Delivery arriving

WhatsApp:

Order confirmation message
Status updates
Payment instructions

12.3 External Systems

Accounting Integration:

Export daily sales
Receipt data for bookkeeping
Tax reporting

Inventory Integration:

Deduct ingredients on order
Low stock alerts
Menu item availability

Loyalty Programs:

Points accumulation
Reward redemption
Customer tier tracking

Part 13: Operational Scenarios

13.1 Scenario: Busy Lunch Rush (Fast Food)

Context: Fast food restaurant, high volume, kiosk and counter orders

Flow:
1. Multiple kiosk customers ordering simultaneously
2. Counter staff handling walk-up orders
3. Kitchen receiving continuous order stream
4. KDS showing all orders, sorted by time
5. Customer display calling numbers as ready
6. Staff managing cash payments from kiosk

Key Requirements:
- Handle concurrent checkout sessions
- Efficient kitchen ticket printing
- Clear order number visibility
- Quick cash confirmation workflow

13.2 Scenario: Dinner Service (Fine Dining)

Context: Fine dining, multi-course meals, tabs for all tables

Flow:
1. Server opens tab when seating guests
2. Server enters first course order
3. Kitchen prepares, expeditor controls timing
4. Guests request more drinks (added to tab)
5. Main course ordered and added
6. Dessert ordered and added
7. Guest requests bill (print bill, not receipt)
8. Guest pays (card or cash)
9. Tab closed, receipt printed

Key Requirements:
- Tab management for multiple courses
- Expeditor control of kitchen flow
- Bill vs receipt distinction
- Graceful discount application if needed

13.3 Scenario: App Delivery Order

Context: Customer ordering via app for delivery

Flow:
1. Customer browses menu in app
2. Adds items to persistent cart
3. Proceeds to checkout
4. Enters/confirms delivery address
5. Sees delivery fee added
6. Selects wallet payment
7. Confirms order
8. Receives confirmation with estimated time
9. Kitchen prepares
10. Driver picks up
11. Customer receives push notification
12. Order delivered

Key Requirements:
- Server-side cart persistence
- Address validation
- Delivery fee calculation
- Push notification integration
- Driver handoff tracking

13.4 Scenario: WhatsApp Order (Pickup)

Context: Customer ordering via WhatsApp for pickup

Flow:
1. Customer messages kitchen number
2. Chatbot greets, shows menu
3. Customer specifies items
4. Chatbot confirms order and total
5. Customer selects USSD payment
6. Chatbot sends USSD instructions
7. Customer completes payment on phone
8. Webhook confirms payment
9. Chatbot confirms with estimated time
10. Kitchen prepares
11. Customer arrives and picks up

Key Requirements:
- Chatbot conversation management
- USSD payment initiation
- Webhook handling
- WhatsApp message confirmation

13.5 Scenario: Voiding Items

Context: Customer changes mind after ordering

Flow:
1. Order placed and sent to kitchen
2. Customer says "Actually, no burger"
3. Server voids burger from order
4. System checks: Is discount needed? Does void need approval?
5. Manager approves void (if required)
6. Void ticket printed to kitchen
7. Kitchen stops/discards burger preparation
8. Order total updated
9. When paying, adjusted total used

Key Requirements:
- Void permission by role
- Manager approval workflow
- Void ticket to kitchen
- Order total recalculation
- Audit trail of void

13.5 Scenario: Table QR Self-Ordering

Context: Customer at table orders via QR code on their phone

Flow - Web (No App):
1. Customer sits at Table 7
2. Scans QR code on table tent
3. Browser opens: menu.jikoxpress.com/mamalishe?table=7
4. Sees Mama Lishe's menu (no login needed)
5. Browses, adds: 1x Ugali + Samaki, 1x Juice
6. Taps "View Cart" → sees items and total: 18,500
7. Taps "Checkout"
8. Table number shown: "Table 7" (from QR, read-only)
9. Payment options: USSD or Cash
10. Selects USSD, enters phone: 0754xxxxxx
11. Receives USSD prompt on phone
12. Confirms payment
13. Browser shows: "Order #34 Confirmed! Your food will be delivered to Table 7"
14. Kitchen receives order with Table 7 clearly marked
15. Staff delivers food to Table 7

Flow - App User:
1. Customer scans QR at Table 7
2. Has app installed → app opens with table=7
3. Customer already logged in
4. Browses menu, adds items
5. Checkout shows Table 7
6. Payment options include: Wallet (12,500 balance), USSD, Cash
7. Selects Wallet
8. Instant payment from balance
9. Order confirmed, push notification enabled
10. When ready: Push notification "Your order #34 is ready!"
11. Staff delivers to Table 7

Flow - Cash Payment:
1. Customer scans QR, orders via web
2. Selects "Pay at Counter"
3. Order created (status based on kitchen config)
4. Screen shows: "Please pay 18,500 TZS at counter. Order #34"
5. Customer walks to counter, pays cash
6. Staff sees pending cash order, confirms payment
7. If KITCHEN_FIRST: Food already preparing
8. If PAYMENT_FIRST: Kitchen now receives order
9. Food delivered to table

Key Requirements:
- QR contains kitchen ID + table number
- Web menu works without app or login
- Table number locked (customer can't change)
- USSD and Cash always available
- Wallet only if app + logged in
- Kitchen ticket clearly shows table number

13.6 Scenario: Kwa Deni (Credit Customer)

Context: Regular trusted customer wants to take food on credit

Flow - Creating Debt:
1. Regular customer (registered) orders lunch
2. Customer says "Nitalipia kesho" (I'll pay tomorrow)
3. Staff checks customer is registered in system
4. Staff navigates to hidden Kwa Deni option
5. System checks:
   - Kwa Deni enabled for this kitchen ✓
   - Staff has credit permission ✓
   - Customer registered ✓
   - Customer within credit limit ✓
6. Order total: 15,000
7. Customer current balance: 10,000
8. New balance would be: 25,000 (within limit of 50,000) ✓
9. Staff confirms credit transaction
10. Order created, kitchen prepares food
11. Customer receives food and leaves
12. Debt of 15,000 added to customer account

Flow - Paying Debt (partial):
1. Same customer returns 3 days later
2. Customer: "Nataka kulipa 20,000" (I want to pay 20,000)
3. Staff looks up customer, sees balance: 25,000
4. Customer pays 20,000 cash
5. System records debt payment
6. New balance: 5,000
7. Receipt printed showing payment toward credit

Flow - Paying Debt (full):
1. Customer returns next week
2. Wants to clear balance completely
3. Staff shows remaining balance: 5,000
4. Customer pays 5,000
5. Balance now: 0
6. Customer in good standing for future credit

Key Requirements:
- Hidden UI (not visible to regular staff or customers)
- Permission checks at multiple levels
- Clear balance tracking
- Partial payment support
- Receipt differentiation (credit vs regular)

13.7 Scenario: Split Table (Edge Case)

Context: Two friends at one table want separate bills

Options:

Option A: Separate Tabs
1. Create two tabs for same table (e.g., Table 5A, Table 5B)
2. Each person's orders on their tab
3. Close tabs separately

Option B: Manual Split at Payment
1. Single tab with all orders
2. At payment, staff calculates each portion manually
3. Process two payments against same tab
4. Close tab when fully paid

Recommendation: Start with Option B (manual) for V1, as true split adds significant complexity.

Part 14: Non-Functional Requirements

14.1 Performance

Checkout session creation: < 200ms
Kitchen notification: < 500ms from trigger
Print job creation: < 200ms
Payment processing: Depends on provider, show progress
KDS refresh: Real-time (websocket or < 2s polling)

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 1000+ orders per day per kitchen
Support multi-location kitchens (future)

14.4 Security

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

14.5 Compliance

Tax calculation accuracy
Receipt format compliance (local regulations)
Payment provider compliance
Data retention policies

Part 15: Future Considerations

15.1 Planned for Later Versions

Partial Payments:

Allow split payments (50% wallet, 50% cash)
Track multiple payment records per transaction

Table Management:

Table entity with capacity, zone, status
Reservation integration
Table transfer (move tab to different table)

Inventory Integration:

Ingredient deduction on order
Menu item availability based on stock
Low stock alerts

Loyalty Program:

Points earning on purchase
Points redemption
Customer tiers and benefits

Multi-Location:

Kitchen groups/chains
Centralized menu management
Cross-location reporting

15.2 Out of Scope for Current Phase

Third-party delivery integration (Uber Eats, etc.)
Advanced reservation system
Kitchen video display
Customer feedback/rating system
Advanced analytics dashboard

Appendix A: Glossary

Term	Definition
Tab	A container for unpaid orders at a dine-in table
Kwa Deni	Credit/debt system - customer takes food and pays days/weeks later
Table QR	QR code at table that customers scan to self-order via phone
Stub	Small printed slip with order number for customer
KDS	Kitchen Display System - digital screens showing orders
Expeditor	Senior kitchen staff who controls order flow
Station	A specific preparation area in the kitchen
Bump	Mark an order as complete on KDS
Fire	Send order to kitchen for preparation
Void	Cancel an item from an order
Kitchen Wallet	Prepaid balance issued by kitchen to loyal customers
App Wallet	Platform-wide customer wallet
Deep Link	URL that opens directly in mobile app if installed

Appendix B: Configuration Checklist

When setting up a new kitchen, configure:

Appendix C: Decision Log

Key architectural decisions made during design:

Decision	Choice	Rationale
Tab vs modify order	Multiple orders per tab	Cleaner for kitchen, independent lifecycles
Tab creation	Auto-create on first pay-later order	Less friction for staff
Partial payments	Defer to V2	Complexity vs actual need
Kwa Deni visibility	Hidden by default	High-risk feature, prevent misuse
Kwa Deni partial payment	Supported	Real-world need for debt repayment
Print architecture	Client pull model	Works with local printers, offline support
Order number	Daily reset	Easier for kitchen communication
Receipt number	Never reset	Accounting/compliance requirement
Kitchen timing	Configurable per channel	Different trust models for different channels

Document History

Version	Date	Author	Changes
1.0	December 2024	Architecture Team	Initial document

End of Document