MezbanPOS — Software Documentation

Product overview, features, and behavior of the MezbanPOS desktop application.

MezbanPOS — Detailed Software Documentation

A complete restaurant management platform: local-network desktop POS + Mezban Cloud web dashboard and backend.

About This Document

  • Sections 1–19 describe the MezbanPOS desktop application (Electron + React + SQLite): product overview, features, and behavior. The desktop app runs on Windows, macOS, and Linux and can operate fully offline on a local network, or connect to Mezban Cloud for sync, license validation, and the web dashboard.
  • Section 20 describes Mezban Cloud — the cloud backend (Express + PostgreSQL + WebSocket) and web dashboard at app.mezbanpos.com.

Table of Contents

  1. What Is MezbanPOS?
  2. How It Works
  3. User Roles & Access
  4. Authentication
  5. Point of Sale (POS)
  6. Payment & Checkout
  7. Kitchen Display System (KDS)
  8. Menu Management
  9. Floor Plan & Tables
  10. Order History & Management
  11. Customer Database
  12. Shift Management
  13. Reporting & Analytics
  14. Settings & Configuration
  15. Printing
  16. Backup & Recovery
  17. Multi-Device / Local Network
  18. Audit Logging
  19. License Management
  20. Mezban Cloud

1. What Is MezbanPOS?

MezbanPOS is a desktop Point of Sale application designed to run on a local network inside a restaurant or fast food shop. It is built with Electron, which means it runs as a native application on Windows, macOS, and Linux — no browser, no internet, no cloud subscription required.

The software covers the full order lifecycle:

  • A cashier takes an order at the counter or for a table
  • The order appears instantly on the kitchen screen
  • Kitchen staff mark items as in-progress and ready
  • The cashier collects payment and prints a receipt
  • Managers review sales reports and shift summaries
  • All data lives on a single machine (or shared via LAN)

2. How It Works

MezbanPOS runs in one of three modes:

Mode Description
Standalone Single terminal. Everything runs locally — no network setup needed.
Server Mode This terminal hosts the database, REST API, and WebSocket server on port 3737. All other devices connect to it.
Client Mode This terminal connects to a Server terminal over LAN/WiFi by entering the server's IP address.

In a multi-terminal setup, one machine acts as the hub. All order data, the menu, and settings live on that machine. Secondary terminals (POS counters, kitchen screens) connect to it and receive real-time updates over WebSocket.

Technology used under the hood:

  • SQLite database (via Drizzle ORM)
  • Express HTTP server for REST API
  • WebSocket server for real-time events
  • Electron for the desktop shell
  • React for the UI
  • Zustand for local state management

3. User Roles & Access

Every staff member has a PIN-protected account assigned one of four roles.

Role What They Can Do
Admin / Owner Everything: settings, user management, reports, menu, POS, KDS, shifts, floor plan
Manager POS, KDS, Menu, Floor Plan, Reports, Shifts — but not user management or system settings
Cashier / Staff POS order taking and payment only
Kitchen Staff Kitchen Display System (KDS) view only — can update order status

Role enforcement happens on every page/route. A cashier who navigates directly to the reports URL is redirected back to the POS.

4. Authentication

How login works:

  • The login screen shows all active staff as tiles
  • Staff tap their name, then enter a 4–6 digit PIN
  • The PIN is hashed with SHA-256 and compared against the stored hash
  • After 5 consecutive wrong PINs, the account is locked for 5 minutes
  • No internet connection is ever required

User management (Admin/Manager only):

  • Create users with a name, role, and PIN
  • Change a user's PIN at any time
  • Deactivate users (soft delete — records are preserved)

Manager Override:

  • Certain actions (void, refund) performed by a cashier require a manager or admin to enter their own PIN in a modal to authorize the action
  • This is logged in the audit trail

5. Point of Sale (POS)

The POS is the primary daily-use screen. It is divided into a left panel (menu/cart) and a right panel (order summary/payment).

5.1 Taking an Order

Order Types:

  • Dine-In — Requires table selection and optionally server assignment
  • Takeout — No table needed; fast counter orders
  • Delivery — Requires customer phone number; address is auto-filled from the customer database

Browsing the Menu:

  • Categories are displayed as tabs at the top
  • Items display with name and price
  • Unavailable (86'd) items are hidden; a toggle reveals them

Customizing an Item: When an item is tapped, a customization modal opens:

  • Choose a variant (e.g., Small, Medium, Large — each with a price modifier)
  • Select modifiers/toppings (e.g., extra cheese, no onions — each with an optional extra charge)
  • Add per-item notes

5.2 The Cart

The cart shows all items added to the current order:

  • Adjust quantity with + / – buttons
  • Remove individual items
  • Add item-level notes inline
  • Apply a flat discount amount
  • Look up a customer by phone number (for delivery orders)

5.3 Hold & Recall Orders

  • Any in-progress order can be put on hold and saved
  • A cashier can recall any held order from the "Open Orders" modal
  • This allows managing multiple tables or customers simultaneously

5.4 86'd Items (Availability Toggle)

  • Any menu item can be quickly marked as unavailable ("86'd")
  • 86'd items are hidden from the ordering screen
  • Kitchen or managers can toggle availability in real time

6. Payment & Checkout

Tapping "Charge" on the cart opens the payment modal.

6.1 Payment Methods

Cash:

  • Enter the amount tendered
  • Change is calculated and displayed automatically
  • Quick-amount buttons round up to the nearest $5, $10, $20, or $50

Card:

  • Record a card payment manually (no terminal integration)
  • Optional tip entry (preset percentages: 10%, 15%, 20%, or custom amount)

Split Payment:

  • Pay part by card, part by cash
  • Card portion handles tip; cash portion calculates change
  • Each portion can have its own tax rate applied (configurable in settings)

6.2 Tax Calculation

Tax is calculated with support for overrides at multiple levels:

Level Description
Global Default Applied to all items by default
Payment Method Different rates for cash vs card (e.g., pass card fee to customer)
Per Category Override rate for an entire category (e.g., beverages)
Per Item Override rate for a specific menu item

When a split payment is made, the weighted average tax rate is applied proportionally.

6.3 Tips

  • Tips are recorded per order
  • Only available on card payments
  • Totals appear in shift reports and analytics

6.4 Shift Requirement

  • A shift must be open before any payment can be processed
  • If no shift is open, a warning banner appears on the POS with an "Open Shift" button
  • This prevents untracked sales

7. Kitchen Display System (KDS)

The KDS is designed to run on a dedicated screen in the kitchen, preferably a large touchscreen.

How It Works

  • Orders appear the moment they are placed at the POS
  • The screen is divided into three columns: Pending, In Progress, Ready
  • Kitchen staff tap an order card to advance its status
  • When an order is Ready, the cashier is notified and can begin the handoff

Order Cards Show:

  • Order number and type (Dine-In / Takeout / Delivery)
  • Table number (for dine-in)
  • List of items with quantities, variants, modifiers, and notes
  • Elapsed time since the order was placed

Real-Time Updates:

  • Powered by WebSocket — new orders appear instantly without refreshing
  • An audio alert (beep) plays when a new order arrives
  • If the WebSocket disconnects, the screen falls back to polling every 30 seconds
  • A live/offline connection indicator is always visible

8. Menu Management

Accessible to Admin and Manager roles.

Categories

  • Create, edit, and delete categories
  • Assign a display color for visual organization
  • Set sort order to control how they appear on the POS
  • Set a per-category tax rate override
  • Toggle active/inactive
  • Create items with name, description, and base price
  • Upload an item image (stored locally on the server machine)
  • Assign to a category
  • Set a per-item tax rate override
  • Toggle active/inactive (inactive items are hidden on POS)

Variants

Each item can have multiple variants with price modifiers:

  • Example: "Medium" (+$0), "Large" (+$2.50), "Family" (+$5.00)
  • The cashier selects a variant when adding an item to the cart

Modifiers / Toppings

Each item can have modifiers:

  • Example: "Extra Cheese" (+$1.00), "No Onions" (+$0.00)
  • Can be marked required (must select) or optional
  • Supports multiple selections

9. Floor Plan & Tables

Floor Plan Editor (Admin/Manager)

A visual drag-and-drop editor lets you lay out your dining room:

  • Add tables in three shapes: round, square, rectangle
  • Set table number, label, and seat count
  • Position and resize tables on the canvas
  • Assign a rotation angle
  • Assign a server to each table

Live Table View

When not in edit mode, the floor plan shows real-time table status:

  • Available — green, ready for seating
  • Occupied — red, has an open order
  • Reserved — yellow

Tapping an occupied table from the POS opens that table's order directly.

10. Order History & Management

A full searchable log of every order. Accessible to Admin and Manager.

Browsing Orders

  • Quick filter: Today, Yesterday, Last 7 Days, Last 30 Days
  • Full-text search across order number, customer name, etc.

Per-Order Detail View

  • All items, quantities, variants, modifiers
  • Subtotal, discount, tax, total
  • Payment method, amount paid, change given
  • Who created the order and when

Actions

Void Order:

  • Cancels the entire order
  • Requires a reason to be entered
  • If done by a cashier, requires a manager PIN override
  • Logged in the audit trail

Refund Item:

  • Refund one or more items from an order
  • Specify quantity and reason
  • Requires manager authorization if performed by cashier
  • Logged in audit trail

Reprint Receipt:

  • Print a receipt for any historical order

11. Customer Database

A simple customer address book used primarily for delivery orders.

Features

  • Search customers by name or phone number
  • View full customer record: name, phone, address, notes
  • View all past orders for a customer
  • Create, edit, or delete customer records

Auto-Creation at Checkout

When a delivery order is placed and the customer's phone number is not found:

  • The system creates a new customer record automatically during checkout
  • Subsequent deliveries to the same number auto-fill their address

12. Shift Management

Shifts track a working period — typically one staff member's time at the register.

Opening a Shift

  • Enter the opening float (cash already in the drawer)
  • System records who opened it and when

Closing a Shift

  • Count the actual cash in the drawer
  • System calculates: expected cash = opening float + cash sales
  • Displays whether the drawer is balanced, over, or short
  • Add optional notes
  • Option to trigger an automatic database backup on close

Shift Report

  • Total orders taken
  • Cash sales vs card sales breakdown
  • Total discounts applied
  • Total tips collected
  • Who opened and closed the shift
  • Printable

13. Reporting & Analytics

Accessible to Admin and Manager. Covers sales data from any time window.

Summary Cards

Metric Description
Total Revenue Sum of all paid orders in the period
Order Count Number of completed orders
Average Order Value Revenue ÷ orders
Voids Number and total value of voided orders
Refunds Number and total value of refunded items
Tips Total tips collected

Charts

  • Daily Revenue Bar Chart — bar per day showing revenue
  • Daily Order Count — alongside the revenue chart
  • Time periods: Last 7 days, Last 14 days, Last 30 days

Top Items

  • The 8 best-selling items ranked by quantity sold and revenue generated

Export

  • CSV Export — raw sales data saved to a file on disk
  • PDF Export — formatted report saved to a file on disk

14. Settings & Configuration

Accessible to Admin only.

Shop Settings

Setting Description
Shop Name Displayed on receipts
Currency Symbol e.g., $, €, £, ₹
Default Tax Rate Applied to all items unless overridden
Cash Tax Rate Tax rate when paying by cash
Card Tax Rate Tax rate when paying by card
Receipt Footer Text Custom message at bottom of receipts
Starting Order Number Set where order numbering begins

Terminal Mode

  • Set this terminal to Standalone, Server, or Client mode
  • In Client mode: enter the Server terminal's IP address
  • Port: default 3737 (configurable)

Printer

  • Select from detected system printers
  • Choose paper width: 80mm or 58mm
  • Auto-print receipts: Ask / Always / Never
  • Send a test print to verify setup

Floor Plan

  • Enable or disable the table floor plan feature

Backup

  • Choose a backup directory (USB drive, cloud-synced folder, etc.)
  • Set number of backups to keep (default: 10)
  • Toggle auto-backup when a shift is closed
  • Trigger a manual backup immediately
  • View when the last backup was taken

User Management

  • Create staff accounts (name, role, PIN)
  • Change any user's PIN
  • View all users with their roles

15. Printing

MezbanPOS prints to any system printer that supports standard thermal receipt formatting.

What Can Be Printed

  • Customer Receipt — after payment (auto-print or prompted)
  • Bill / Pre-payment Receipt — print before collecting payment
  • Shift Report — end-of-shift summary
  • Historical Receipt — reprint any past order

Receipt Contents

  • Shop name and header
  • Order number, date/time, order type
  • Cashier name
  • Itemized list with variants, modifiers, and notes
  • Subtotal, discount, tax, tip, and total
  • Payment method and change given
  • Custom footer text

Printer Setup

  • Select any installed system printer from settings
  • Paper widths supported: 80mm and 58mm
  • Test print available from settings

16. Backup & Recovery

How Backups Work

  • MezbanPOS creates a copy of the SQLite database file
  • Backups are saved to a user-chosen directory
  • File name includes a timestamp for easy identification
  • Old backups are automatically deleted when the count exceeds the configured limit

Backup Triggers

Trigger Description
Manual Press "Backup Now" in Settings
Shift Close Automatic if enabled in Settings
Startup Check If last backup is more than 24 hours old, prompts a reminder

Recovery

To restore from a backup, replace the current database file with a backup copy. The backup files are plain SQLite files — no proprietary format.

17. Multi-Device / Local Network

MezbanPOS is designed to work across multiple devices over a shared WiFi or wired LAN — no internet required.

Typical Setup

┌──────────────────────────────────────────────────┐
│                 LOCAL NETWORK                    │
│                                                  │
│  ┌─────────────────┐    ┌──────────────────────┐ │
│  │  MAIN REGISTER  │    │  KITCHEN SCREEN      │ │
│  │  (Server Mode)  │◄──►│  (Client Mode)       │ │
│  │                 │    │                      │ │
│  │ • Database      │    │ • KDS view only      │ │
│  │ • Express API   │    │ • Connects by IP     │ │
│  │ • WebSocket hub │    │ • Real-time updates  │ │
│  └─────────────────┘    └──────────────────────┘ │
│                                                  │
│       Optional: additional POS terminals         │
└──────────────────────────────────────────────────┘

WebSocket Real-Time Events

Event Triggered When
order:new An order is placed at any terminal
order:status_changed Kitchen staff advances order status
order:settled Payment is collected
menu:updated Menu item or category is changed

All connected clients receive these events instantly.

Standalone Web KDS

The server also hosts a lightweight browser-based KDS page at http://<server-ip>:3737/kds that any device on the network can open — including tablets not running the full Electron app.

18. Audit Logging

Every destructive action is recorded in a tamper-evident audit log.

What Is Logged

  • Order voids — who requested, who authorized, reason, timestamp, amounts
  • Item refunds — same fields plus which items and quantities were refunded

Who Can Review Logs

  • Admin and Manager can view the audit trail per order in the Order History page

Manager Authorization

  • If a Cashier initiates a void or refund, a modal appears requiring a Manager or Admin to enter their PIN
  • Both the requesting user and the authorizing user are recorded in the log

19. License Management

MezbanPOS includes a built-in licensing system.

State Meaning
Trial Running within the trial period; all features available
Active Valid license key applied; full access
Grace License expired but within a short grace window
Expired Trial or license has ended; limited functionality
Tampered License data has been modified; invalid
  • A license banner appears in the UI when the trial is active or expiring
  • Activation is done by entering a license key in Settings
  • License is bound to the machine's hardware fingerprint

20. Mezban Cloud

Mezban Cloud is the cloud backend and web dashboard platform that powers app.mezbanpos.com. It runs on a DigitalOcean droplet behind nginx and consists of:

  • Express API — REST + WebSocket on port 4000 (proxied at /api/)
  • PostgreSQL database — cloud source of truth, multi-tenant
  • Next.js web dashboard — serves the restaurant management UI at app.mezbanpos.com

The desktop Electron app and the web dashboard both talk to the same cloud API. The desktop app authenticates with an API key; the web dashboard uses email + password (JWT in a secure httpOnly cookie).

20.1 Architecture

app.mezbanpos.com
├── /          → Web Dashboard (Next.js, port 3000)
└── /api/      → Cloud API     (Express, port 4000)

Authentication:
  Electron desktop terminals  → Bearer <api_key>  (UUID per restaurant)
  Web dashboard sessions      → Bearer <JWT>       (email + password)

Every table in the PostgreSQL database includes a restaurant_id column — all data is scoped per restaurant account. There is no cross-account data access.

20.2 Plans

Plan Description
Trial Full access to all cloud features during the evaluation period
Basic Core cloud features — web dashboard, sync, reports
Pro Everything in Basic plus desktop app download, unlimited data retention, and priority support

Upgrade and billing are managed from within the web dashboard at app.mezbanpos.com.

20.3 Web Dashboard

The web dashboard at app.mezbanpos.com gives restaurant owners and managers full access to their restaurant data from any browser. No desktop app installation is required.

Signup / Login:

  • Create a restaurant account at app.mezbanpos.com/signup with email, password, and shop name
  • Log in at app.mezbanpos.com/login
  • Authentication uses JWT stored in a secure httpOnly cookie — no manual token handling

Dashboard Overview:

  • Today's revenue, order count, and average order value at a glance
  • API key display — copy this into the desktop app's Settings → Terminal Mode to link the desktop POS to the cloud
  • Recent order feed with status indicators

Orders:

  • Full searchable order list with filters by date, type, and status
  • Per-order detail: items, variants, modifiers, payment method, total, cashier

Menu (read + edit):

  • Browse and edit categories, items, variants, and modifiers
  • Toggle item availability (86'd) from the dashboard
  • Changes sync to all connected desktop terminals in real time via WebSocket

Settings:

  • Edit shop name, currency symbol, default tax rate, and receipt footer
  • Manage staff accounts: create, edit, deactivate, reset PINs
  • Assign roles and permissions

20.4 Roles & Permissions (Cloud)

The cloud backend supports fully customisable roles beyond the four system defaults. Role permissions are stored as a JSON array per role row and enforced on every API request.

System Role Default Access
Admin / Owner All API routes — settings, users, menu, orders, reports, accounting
Manager Menu, orders, KDS, reports — no user management
Cashier / Staff POS order create/update, payment — read-only elsewhere
Kitchen Staff Order status updates only (KDS)

Custom roles can be created via the web dashboard with any combination of granular permissions.

20.5 Inventory & Recipe Management

The cloud backend includes a full inventory module linked to the menu.

Ingredients:

  • Define ingredients with unit of measure (kg, g, litre, piece, etc.)
  • Set current stock quantity and low-stock threshold
  • Low-stock alerts appear in the dashboard when stock falls below threshold

Recipes:

  • Link menu items to a list of ingredients and quantities
  • When an order is placed, stock is automatically deducted based on the recipe
  • Recipe builder is accessible under Menu → Recipes in the web dashboard

Vendor Management:

  • Maintain a directory of ingredient suppliers with contact details
  • Raise purchase orders against vendors to replenish stock
  • Purchase receipts update ingredient stock quantities automatically

20.6 Accounting & Expenses

The cloud platform includes a general ledger and expense tracking module built for restaurant operators who want a clear picture of profitability without a separate accounting tool.

Expense Categories:

  • Define categories (e.g. Electricity, Rent, Staff Salaries, Raw Materials)
  • Assign a default accounting account code per category

Expense Logging:

  • Record individual expenses with amount, date, category, vendor, and notes
  • All expenses appear in the profit and loss summary in Reports

General Ledger:

  • Double-entry accounting entries are created automatically for orders, refunds, shifts, and expenses
  • View ledger entries by date range and account type
  • Export as CSV or PDF for your accountant

20.7 FBR & Tax Compliance

The cloud backend includes an FBR (Federal Board of Revenue) compliance module designed for restaurants operating in Pakistan under the PRAL / POS integration scheme.

  • FBR invoice numbering — sequential FBR invoice numbers are attached to each order
  • FBR QR code — a QR code linking to the FBR verification portal is generated per receipt
  • Monthly FBR summary — export the full monthly FBR transaction log in the required format
  • PRA / SRB split — separate reporting for Punjab (PRA) and Sindh (SRB) tax authorities where applicable

FBR settings are configured under Settings → Tax & FBR in the web dashboard.

20.8 Discount Codes & Promotions

Create and manage promotional codes from the web dashboard.

Code Types:

  • Percentage discount — e.g. 10% off the order total
  • Flat amount discount — e.g. Rs 200 off

Controls:

  • Set a usage limit (e.g. first 100 redemptions only)
  • Set an expiry date
  • Enable or disable a code at any time

Codes can be applied at POS checkout or on the online ordering website (when launched). Usage stats are visible in Reports → Discount Codes.

20.9 Desktop ↔ Cloud Sync

When the desktop Electron app is connected to Mezban Cloud, data flows between the local SQLite database and the cloud PostgreSQL database.

What syncs:

  • Menu categories, items, variants, modifiers — changes made on either side propagate to the other
  • Orders — placed at any terminal appear in the cloud within seconds via WebSocket
  • Settings — shop name, tax rates, currency, receipt footer
  • Users — staff accounts and PIN changes

How it works:

  • The desktop app connects to the cloud API using its unique API key (set in Settings → Terminal Mode → Cloud Mode)
  • Each syncable record carries a sync_id (UUID) so the same object can be matched across SQLite and PostgreSQL
  • On reconnect, a sync flush sends any locally queued changes to the cloud

Offline behaviour:

  • If the internet connection drops, the desktop app continues to operate fully offline
  • All order-taking, payment, and printing work without interruption
  • A sync queue accumulates changes and flushes automatically on reconnect

20.10 API Reference (Summary)

All cloud API endpoints are prefixed at /api/. Authentication is required for all routes except /api/auth and /api/public.

Route prefix Description
POST /api/auth/signup Create a new restaurant account
POST /api/auth/login Log in (returns JWT)
GET /api/orders List orders (paginated, filterable)
POST /api/orders Create a new order
GET /api/categories List menu categories
GET /api/menu-items List menu items
GET /api/shifts List shifts
POST /api/shifts Open a new shift
GET /api/reports Sales summary (daily/weekly/monthly)
GET /api/customers List customers
GET /api/users List staff accounts
GET /api/roles List roles and permissions
GET /api/inventory Ingredient stock levels
GET /api/recipes Item-to-ingredient recipe mappings
GET /api/vendors Vendor directory
GET /api/purchases Purchase orders
GET /api/expenses Expense log
GET /api/accounting General ledger entries
GET /api/fbr FBR invoice log
GET /api/discount-codes Promotional codes
GET /api/audit-log Audit log (voids, refunds)
POST /api/sync Desktop sync flush endpoint
GET /api/license License status for this restaurant

For a full API reference including request/response schemas, contact support at husnain.ahmed@mezbanpos.com.

20.11 Support & Contact

For questions about Mezban Cloud, billing, or the web dashboard: