Software Requirements Specification (SRS)

Product: Restaurant OS SaaS — Dynamic QR-Based Multi-Vendor Restaurant Operating System Version: 1.0.0 Status: Draft — pre-implementation Audience: Solution architects, engineering leads, product managers, founders

1. Introduction

1.1 Purpose

This document specifies the functional and non-functional requirements for a multi-tenant Restaurant Operating System. It replaces fragmented POS systems, static digital menus, and isolated kitchen displays with one unified platform that spans the full order lifecycle: customer ordering via table QR, kitchen preparation, waiter service, cashier billing, inventory deduction, and business analytics.

1.2 Scope

The system is a SaaS platform, not a single-restaurant application. One codebase and one deployment serve an arbitrary number of independent restaurants ("tenants"), each with one or more branches, each branch with its own tables, staff, and inventory. Tenant data is logically and technically isolated (restaurant_id boundary, enforced by database Row Level Security — not just application code).

The scope spans customer-facing ordering, staff-facing operations (kitchen, waiter, cashier), back-office management (menu, inventory, staff, analytics), platform administration (tenant/subscription management), and a later AI intelligence layer.

1.3 Out of Scope (for MVP)

AI features, supplier/procurement management, full CRM, advanced multi-branch central reporting, WhatsApp ordering automation, and complex POS features (split billing, table merging) are explicitly deferred to post-MVP phases. See 07-ROADMAP-PHASES.md for phase boundaries.

1.4 Definitions

2. Overall Description

2.1 Product Perspective

The platform has four distinct application surfaces sharing one backend and one database:

1. Customer Storefront — mobile-first, PWA, reached via QR scan, no login required initially.
2. Staff Apps — Waiter (tablet-first PWA), Kitchen/KDS (large-screen-first, kiosk-friendly), Cashier/POS.
3. Restaurant Admin Dashboard — desktop-first, for owners/managers to configure menu, staff, tables, and view analytics.
4. Platform Admin — super-admin console for managing tenants, subscriptions, and platform-wide settings.

2.2 Product Functions (summary)

• Dynamic, token-based QR table resolution (no hardcoded table URLs)
• Real-time menu browsing with categories, variants, modifiers, images
• Ingredient/allergen transparency and personalized allergy safety checks
• Cart, checkout, and order placement with server-side price authority
• Real-time order propagation to kitchen, waiter, and cashier simultaneously
• Kitchen Display System with station-based order routing
• Waiter shift and table assignment tracking
• Cashier/POS billing with pluggable payment methods
• Restaurant admin dashboard: menu CMS, table map, staff, analytics
• Inventory deduction via recipe BOM (post-MVP)
• Multi-branch central management (post-MVP)
• AI-assisted recommendations, forecasting, and natural-language BI (future phase)

2.3 User Classes and Characteristics

See Section 3 for the full actor/role list. In summary: platform super admin; restaurant owner/admin/branch manager; cashier; waiter; kitchen staff; inventory manager; accountant; and the anonymous/guest customer (account optional).

2.4 Operating Environment

Web-based, responsive across mobile (customer, waiter), tablet (waiter), and desktop (admin dashboard, KDS on large screens). Installable as a PWA for customer, waiter, and KDS surfaces. Target market includes Bangladesh, so local payment methods (cash, bKash, Nagad, card) must be supported as pluggable providers.

2.5 Design and Implementation Constraints

• Multi-tenancy must be enforced at the database layer via RLS — frontend filtering alone is explicitly disallowed as a security boundary.
• The client never calculates final order totals; the server is the sole source of truth for pricing, tax, discounts, and totals.
• Order status transitions follow a fixed state machine; arbitrary status changes from the frontend are not permitted.
• No Redis / Socket.io in the MVP architecture — Supabase Realtime is used first; a dedicated realtime layer is only introduced if traffic genuinely requires it.
• Supabase service keys must never be exposed to browser/client code (they bypass RLS).

3. Actors and Roles

3.1 Platform Level

Super Admin — manages restaurants (tenants), subscriptions, plans, system settings, platform-wide analytics, platform users, support, and feature flags.

3.2 Restaurant Level

3.3 Customer

No account is required for initial QR ordering. An optional customer account may be added later for order history, loyalty, and personalization.

4. Functional Requirements

4.1 Multi-Tenancy

• FR-1: The system SHALL support an unlimited number of independent restaurants, each with isolated data.
• FR-2: Every tenant-owned database table SHALL contain restaurant_id directly, or derive it safely through a parent relationship.
• FR-3: Data access SHALL be enforced via PostgreSQL RLS policies keyed off the authenticated user's restaurant membership — not solely by application-level query filters.

4.2 Dynamic QR & Table Resolution

• FR-4: Each physical table SHALL be assigned a persistent, unguessable token (not a raw database ID) embedded in its QR code (e.g. /table?token=<secure-token>).
• FR-5: Scanning a table's QR SHALL resolve, in order: token validity → table → branch → restaurant → create a table_session.
• FR-6: Changing the menu, prices, waiter assignment, or table configuration SHALL NOT require reprinting the QR code.
• FR-7: A table session SHALL support multiple simultaneous customers at one table, track session lifecycle (started, last activity, expiry), and support abandoned-cart handling.

4.3 Menu Management

• FR-8: Admins SHALL be able to create, edit, delete, reorder, and enable/disable menu categories and items.
• FR-9: Menu items SHALL support variants (e.g. Small/Medium/Large with distinct prices) without hardcoding variant logic.
• FR-10: Menu items SHALL support modifier groups/add-ons (e.g. Extra Cheese +50) via a many-to-many modifier structure.
• FR-11: Each menu item SHALL declare its ingredients and associated allergens.

4.4 Allergen & Ingredient Transparency

• FR-12: Customers SHALL be able to select personal allergies from a predefined allergen list.
• FR-13: For each menu item, the system SHALL compute a safety status (SAFE / WARNING / UNSAFE) by cross-referencing the customer's declared allergies against the item's ingredients and allergens.
• FR-14: This feature SHALL be presented as an informational safety aid, explicitly not a medical guarantee.

4.5 Cart & Ordering

• FR-15: Customers SHALL be able to add items (with selected variant, modifiers, quantity, special instructions) to a cart scoped to their table session.
• FR-16: On order placement, the server SHALL independently validate restaurant, table session, menu item availability, variant, and modifiers, and SHALL independently calculate price, tax, discount, and total — client-submitted totals SHALL be ignored.
• FR-17: Order creation SHALL be atomic: order, order items, and the associated kitchen order SHALL be created (and table status updated) in a single transaction, with rollback on any failure.

4.6 Order Lifecycle

• FR-18: Orders SHALL follow a fixed status state machine: PENDING → CONFIRMED → KITCHEN_PREP → READY → SERVED → COMPLETED, with a CANCELLED branch available from PENDING or KITCHEN_PREP per business rules.
• FR-19: Status transitions SHALL only be performed by authorized server-side logic — never by direct arbitrary updates from the frontend.

4.7 Real-Time Propagation

• FR-20: On order creation, the system SHALL notify, in real time, the Kitchen Display System, the assigned Waiter, and the Cashier simultaneously.
• FR-21: Realtime channels SHALL be scoped narrowly (e.g. per branch, per table, per order) rather than broadcast globally, with authorization applied per channel.

4.8 Kitchen Display System (KDS)

• FR-22: The KDS SHALL present orders in columns by status (New, Preparing, Ready, Completed) and support station-based filtering (Grill, Fryer, Pizza, Drinks, Dessert).
• FR-23: New orders SHALL trigger a visual highlight and a configurable audio alert.

4.9 Waiter Operations

• FR-24: The system SHALL track waiter shifts per branch and automatically associate a table's active order with the waiter on active shift for that table.
• FR-25: Waiters SHALL see their assigned tables, active orders and status, and pending table requests (e.g. bill request, call-kitchen).

4.10 Cashier / POS

• FR-26: Cashiers SHALL be able to view orders, process payment (cash, card, mobile banking, online — pluggable by provider), apply discounts and service charges, and issue receipts/refunds.
• FR-27: Payment records SHALL be stored in a provider-agnostic payments abstraction (method, provider, transaction ID, amount, status).

4.11 Admin Dashboard & Analytics

• FR-28: The admin dashboard SHALL surface: today's sales, order count, average order value, active tables, hourly sales, orders by category, top products, waiter performance, and table revenue.
• FR-29: Analytics SHALL initially be computed directly from operational tables (orders, order_items); pre-aggregated/materialized analytics tables are a later optimization, not an MVP requirement.

4.12 Inventory (Post-MVP)

• FR-30: The system SHALL support recipe/BOM definitions per menu item (ingredient + quantity), and SHALL deduct ingredient stock automatically on order completion.
• FR-31: All inventory changes SHALL be recorded as ledger entries (stock_movements) with a type (purchase, sale, adjustment, waste, return, transfer) — inventory quantities SHALL NOT be mutated without a corresponding ledger entry.

4.13 Direct Online Ordering & Delivery System (Without Table QR)

• FR-32: Customers SHALL be able to browse the restaurant menu and place orders for Home Delivery and Takeaway/Pickup directly via the web storefront without requiring a physical table QR token.
• FR-33: Delivery orders SHALL capture customer contact info (Name, Bangladeshi phone number with validation 01XXXXXXXXX) and delivery destination (Street address, Delivery Area/Zone, and special instructions).
• FR-34: Admins SHALL be able to configure Bangladeshi delivery zones with custom delivery fees (e.g. Inside Dhaka ৳60, Outside Dhaka ৳120), minimum order amounts, estimated delivery times, and free delivery thresholds.
• FR-35: Customers SHALL be able to select between Cash on Delivery (COD), Online Payment (bKash, Nagad, Card), or Pay at Counter (for takeaway).
• FR-36: Delivery orders SHALL support a dedicated delivery lifecycle state machine: ORDER_PLACED → CONFIRMED → KITCHEN_PREP → READY_FOR_DISPATCH → OUT_FOR_DELIVERY → DELIVERED.

4.14 Item & Multi-Item Promo / Special Offer QR Campaigns

• FR-37: Admins SHALL be able to generate dynamic Promotional QR Codes targeting a single menu item or a multi-item combo bundle.
• FR-38: Promo campaigns SHALL support discount structures including Percentage Off (e.g. 20% OFF), Fixed Discount (e.g. ৳100 OFF), and Special Combo Pricing.
• FR-39: Promo campaigns SHALL support scheduling with start and end timestamps, maximum redemptions, and custom campaign banners.
• FR-40: Scanning a Promo QR code SHALL resolve the target item or combo bundle directly, display the locked promotional discount with strike-through pricing, and allow the customer to configure variants/modifiers and add directly to cart for instant checkout.

4.15 Multi-Branch Management & Switching

• FR-41: The system SHALL support multiple branches under a single restaurant tenant with a topbar branch switcher, branch-scoped table configurations, active staff allocations, and branch-filtered revenue metrics.

4.16 Dedicated Delivery Rider Portal

• FR-42: Delivery staff SHALL have a dedicated mobile portal (/rider) to view assigned deliveries, initiate 1-click calls to customers, view map destinations, and mark deliveries as completed with live store synchronization.

4.17 Delivery Distance & Transit Estimation

• FR-43: The delivery checkout SHALL calculate estimated transit time and distance (in KM) with automated delivery fee computation.

4.18 Customer Loyalty Rewards & Cashback Coins

• FR-44: Repeat customers SHALL earn loyalty coins on orders (e.g. 5% cashback), check point balances via phone number, and redeem coins directly in the cart drawer.

4.19 Automated SMS & WhatsApp Notification Dispatch

• FR-45: The system SHALL support automated multi-channel customer notifications for order placement, kitchen dispatch, out-for-delivery, and delivery confirmation.

4.20 Post-Meal 5-Star Rating & Customer Feedback

• FR-46: Customers SHALL be presented with an interactive 5-star rating, tag-based review, and feedback comment dialog upon bill payment or order delivery, aggregated into dashboard analytics.

4.21 Split Bill (Equal & Itemized) for Dine-In Tables

• FR-47: Dine-in guests SHALL be able to split table bills equally among N guests or itemize dish costs for individual digital payments.

4.22 Advance Table Booking & Reservation Management

• FR-48: Customers SHALL be able to submit advance table booking requests with date, time slots, and guest counts, managed via an admin reservation timeline.

4.23 AI Smart Upselling & Frequently Paired Combos

• FR-49: The storefront SHALL intelligently recommend high-affinity companion dishes (e.g. Biryani + Borhani) in food detail sheets and cart drawers with 1-click add-to-cart.

4.24 Food Costing (COGS) & Profit Margin Analytics

• FR-50: The system SHALL track ingredient raw material costs (COGS) per menu item and report gross profit margins, high-margin performers, and food cost ratios in dashboard analytics.

4.17 AI Layer (Future Phase)

• FR-43: The system SHALL support natural-language business questions (e.g. "which item made the most revenue this month?") resolved via a constrained pipeline: intent extraction → safe/validated query generation → PostgreSQL execution → LLM-generated explanation. Arbitrary, unvalidated SQL execution by an LLM is explicitly disallowed.
• FR-44: The system SHALL support cross-sell recommendations and demand/inventory forecasting based on order history and pgvector-backed similarity where applicable.

5. Non-Functional Requirements

5.1 Security

• NFR-1: Row Level Security SHALL be enabled on every tenant-exposed table before production data is present.
• NFR-2: Role-based access control SHALL be enforced both in application logic and via database RLS (defense in depth).
• NFR-3: All state-changing requests SHALL be validated server-side with Zod (or equivalent) in addition to any client-side validation.
• NFR-4: File uploads SHALL be validated (type, size) and stored in tenant-scoped storage paths (e.g. restaurant-assets/{restaurant_id}/...).
• NFR-5: Payment webhooks SHALL be signature-verified.
• NFR-6: An audit log SHALL record sensitive actions: price changes, order cancellations, discounts applied, menu deletions, permission changes, inventory adjustments — capturing actor, action, entity, before/after data, IP, and user agent.
• NFR-7: Rate limiting SHALL be applied to public-facing endpoints (notably QR/table resolution and order placement).

5.2 Performance

• NFR-8: The customer menu SHALL NOT block on loading the entire restaurant's data set; initial load SHALL fetch only restaurant identity, categories, and first-visible items, with progressive loading thereafter.
• NFR-9: A loading skeleton SHALL be shown immediately — the customer SHALL never see a blank screen while the menu loads.
• NFR-10: The customer application bundle SHALL NOT include admin application code, and vice versa (route/component boundary separation).
• NFR-11: Lists (orders, menu items, analytics records) SHALL use pagination, lazy loading, or virtualization rather than loading full data sets client-side.

5.3 Reliability & Data Integrity

• NFR-12: Order creation SHALL be transactional and atomic.
• NFR-13: Inventory quantities SHALL always be derivable from an auditable ledger, never from direct blind updates.

5.4 Usability

• NFR-14: The customer storefront SHALL be mobile-first; the admin dashboard desktop-first; the waiter app tablet-first; the KDS large-screen first.
• NFR-15: Motion/animation SHALL respect prefers-reduced-motion and SHALL be used to communicate state, not as decoration on every element.

5.5 Compatibility

• NFR-16: Customer, waiter, and KDS surfaces SHALL be installable as Progressive Web Apps.

5.6 Observability

• NFR-17: Frontend errors, server errors, API errors, realtime errors, and payment failures SHALL be captured by a production error-monitoring platform (e.g. Sentry).

6. External Interface Requirements

• Payment providers: cash (manual), card, and mobile banking (bKash, Nagad) as pluggable providers behind the payments abstraction; providers beyond MVP cash/manual handling to be confirmed before Phase "Cashier/POS" implementation.
• WhatsApp Business integration (Phase — post-MVP): order-link based ordering flow, decoupled from the core order engine via a channel adapter.
• Future LLM provider for the AI/BI layer (Phase — future): provider choice to be confirmed at that phase; must support constrained/tool-based query execution, not free-form SQL generation.

7. Assumptions, Dependencies, and Open Items

These were explicitly flagged as needing definition before implementation begins on the affected areas — they are not yet fully specified:

1. Full permission matrix per role — the role list exists (Section 3.2); the exact permission set per role per module needs to be finalized before Phase 3 (Auth/RBAC).
2. Payment gateway specifics — provider selection, fee handling, and webhook contracts for bKash/Nagad/card need confirmation before the Cashier/POS phase.
3. Order cancellation/refund business rules — which roles can cancel at which status, and refund handling, need explicit sign-off.
4. Accountant role permissions — mentioned in the role list but not yet detailed.
5. Table merge / split-bill rules — flagged as potentially deferrable to post-MVP; needs an explicit decision if merchants require it at launch.

Do not treat this SRS as final for the items above — confirm them before the corresponding phase starts, per 07-ROADMAP-PHASES.md.