The whole system,
end to end.

How to read this

What Menew is

A diner scans a QR code on their table and orders from their phone. Everything else is in service of making that one moment work for the restaurant, the kitchen, the waiter, and the owner.

Menew is a multi-tenant SaaS: one codebase and one database serve many restaurants, each isolated from the others. It is sold to restaurants in Lebanon (and, increasingly, beyond), which shapes a few non-obvious requirements — cash-heavy payment flows, WhatsApp as the default communication channel, full Arabic with right-to-left layout parity, and graceful behaviour on slow or intermittent connections.

There are five kinds of user, and the whole app is organised around them:

• Customer — scans a table QR, browses the menu, orders solo or as a group, tracks the order live, and splits the bill. No login.
• Kitchen — a live order screen that advances tickets through new → preparing → ready → done. Logs in with a private link plus a PIN.
• Waiter — an optional "confirm-before-kitchen" gate; each waiter has their own link and PIN, and every action is attributed to them by name.
• Restaurant Admin — the owner's dashboard: menu, orders, QR codes, staff, settings, analytics. Signs in with email + password.
• Master Admin — that's the operator of Menew itself: onboard restaurants, manage billing, see every client. The platform owner.

One React single-page app renders all five experiences, picking which one to show from the URL. One Supabase project stores everything behind it. That is the entire shape of the system — the rest of this document is detail.

From Sofra to Menew

The product wasn't designed all at once — it was discovered through dozens of build-and-harden cycles. This is the honest sequence, because the scars explain the architecture.

Architecture at a glance

One client, one data boundary, one backend. The cleverness lives in the boundary between them.

The shape in words

The browser runs a React 19 single-page app built with Vite. There is no router library — App.jsx reads window.location.pathname, decides which of the five pages to render, and (for admin pages) verifies the Supabase session before letting anyone in. Navigation is plain history.pushState wrapped in a nav() helper passed down to each page.

Every component talks to the backend through one module: src/data.js. Nothing else imports the Supabase client. That single chokepoint is what makes the security model legible — you can read one file and know every way data can move. It holds the client, all table queries, all RPC wrappers, the auth helpers, and even pure helpers like theme tokens and billing math.

The backend is Supabase — managed Postgres with Row-Level Security, PostgREST for auto-generated REST, Auth for admin logins, and one Deno Edge Function for the privileged operation (creating admin accounts) that must never touch the browser. The app is built to static files and deployed on Vercel from GitHub; vercel.json rewrites all paths to index.html so the client-side router works on hard refreshes.

The data model

A pragmatic hybrid: relational columns for the things you filter and join on, a JSONB obj for everything else.

The obj pattern

Almost every table follows the same layout — a few real columns for indexing and tenancy (id, restaurant_id, slug, created_at) plus a single JSONB obj column holding the full domain object. The app reads .select('obj') and gets back the exact shape it works with in JavaScript, no mapping layer.

-- e.g. an order row
{ id, restaurant_id, created_at, obj: {
    id, orderCode, restaurantSlug, table, members:[…], total,
    orderType, status, statusHistory:[…], customer?, allergy?, … } }

This is why new fields — orderType, customer, allergy, payment status, discounts — shipped repeatedly without a single schema migration: they live inside obj. The trade-off (and a developer will ask) is discussed in the Q&A.

The tables

Two more tables support the system: app_admins and restaurant_members back the identity model (who is a master, who administers which restaurant), and access_devices records which browsers have logged into each station for security visibility.

Identity at three levels

• Real accounts (Supabase Auth) for masters and restaurant admins — email + password, role verified by is_app_admin() / is_restaurant_member().
• Token + PIN for kitchen and waiter stations — no account needed; the unguessable token comes from the URL, the PIN is entered, and both are validated inside the database function. A waiter's token also resolves their name, so attribution is automatic.
• Anonymous for customers — they never log in; they prove they're allowed to read a specific order by knowing its secret orderCode.

The security model

The single most important thing to understand about Menew: the public API key sits in every diner's browser, on purpose — and that is fine, because the database refuses to do anything it shouldn't.

Why the anon key is safe

Supabase's anon key is public by design; it identifies the project, it doesn't authorise anything. Real authorisation is enforced by Row-Level Security (RLS) on every table. After the v72–v73 lockdown, the anon role has no blanket read or write on the sensitive tables. So how does an anonymous customer place an order? Not directly — through a vetted gate.

SECURITY DEFINER as the only door

Every operation a non-admin needs is a Postgres function marked SECURITY DEFINER with a pinned search_path. The function runs with elevated rights, but it does exactly one narrow thing and validates its inputs first. Some load-bearing examples:

• place_customer_order(slug, obj) — the only way an anon customer writes an order. It resolves and stamps the restaurant_id from the slug server-side and clamps the status, so the client can't forge tenancy or skip the waiter gate.
• public_restaurant(slug) — returns the restaurant object with owner PII and billing stripped out in the database. The customer menu and login screen use this; admin pages keep the full object (RLS-gated to members).
• track_order(id, orderCode) / find_table_order(...) — let a customer poll their own order, but only if they present the secret orderCode, and they return the order with the customer block (name / phone / address) removed. A stranger who guesses an id learns nothing about another diner.
• kitchen_* / waiter_* — every station read and write resolves (token, pin) → restaurant_id inside the function. A bad PIN simply resolves to nothing and the action no-ops.

Admins: real accounts, server-side provisioning

Masters and restaurant admins authenticate through Supabase Auth. Creating those accounts is privileged — it needs the service-role key, which must never reach the browser. So account creation lives in the admin-provision Edge Function (Deno), which: verifies the caller is a master using their JWT, then uses the service-role client to create/link the user with must_change_password: true. On first login the app routes them to ForceChangePassword.jsx before the dashboard. The service-role key exists only inside that function's environment.

Smaller, deliberate hardening

• Cryptographic randomness. Anything that acts as an id, code, or credential — order codes, passwords, slugs — is generated with crypto.getRandomValues, not Math.random, because orderCode is a bearer secret and passwords must not be brute-forceable.
• PIN entry that fails closed. Station PIN pads grey out, auto-verify, and wipe a wrong PIN; PINs are masked behind a show/hide toggle in admin and never leaked as placeholder text.
• Device visibility. Every successful station and admin login records a device row (browser/OS hint, stable per-browser id, server-seen IP, first/last seen). A browser cannot read a MAC address or true LAN IP — a hard privacy boundary — so this is the realistic equivalent: an unfamiliar device stands out and the link can be rotated.
• PostgREST cache. Each migration script ends with notify pgrst, 'reload schema' so new RPCs are callable immediately without a restart.

Every file, explained

What each file is for, and how it connects to the rest. Sizes are a rough sense of weight, not a metric.

Four flows that matter

The walkthroughs that show how the pieces connect under load.

① A customer places a solo order

1. Customer opens /menu/<slug>. Menu.jsx calls getPublicRestaurant(slug) → the public_restaurant RPC returns the restaurant without owner PII.
2. They build a cart (prices computed by the shared ItemCustomize math) and confirm.
3. placeOrder() in data.js builds the order object, generates a crypto-random orderCode, and calls place_customer_order(slug, obj).
4. The RPC (running as definer) resolves restaurant_id from the slug, clamps the status, inserts the row, and returns. If the waiter gate is on, status is parked at pending; otherwise new.
5. The customer polls track_order(id, orderCode) for live status; the kitchen polls kitchen_orders(token, pin) and advances it.

② A group orders together (the hard one)

1. Each phone scanning the same table computes the same deterministic session id (ts_<restaurant>_t<table>) and joins one shared table_sessions row.
2. Each device debounces its cart into the session every 800 ms; all devices poll the session every 3 s to see each other's carts.
3. When everyone confirms, confirmSeatAtomic() calls the row-locked confirm_seat function, which marks the seat confirmed and — if all are now confirmed — designates exactly one submitter.
4. The order id is derived deterministically from the session (o_<session>_<createdAt>), so even if the ephemeral session record is clobbered or expires, every device can still find the placed order directly. No phone is ever stranded.
5. Once a device confirms, its seat locks: background cart-sync stops, removing the write that used to cause the race.

③ A waiter confirms before the kitchen sees it

1. With Waiter Mode on, customer orders land at pending — invisible to the kitchen.
2. The waiter opens their personal /waiter/<token>, enters their PIN; waiter_login resolves who they are from the token.
3. They edit freely (the 9 s auto-refresh never clobbers local edits), then Confirm & Send → waiter_set_status(..., 'new') releases it to the kitchen, attributed to them server-side.
4. If they later edit a ticket the kitchen already has, the RPC stamps kitchenNeedsAck; the kitchen card flashes amber until a cook taps "Got it" (kitchen_ack_changes).

④ The master onboards a restaurant

1. Master fills the onboarding form. onboardRestaurant() creates the restaurant row and a crypto-random admin password + kitchen PIN (returned for display only — never stored in the DB).
2. To create the actual login, the client calls the admin-provision Edge Function, which verifies the caller is a master, then uses the service-role key to create the Auth user with must_change_password: true and link them in restaurant_members.
3. Credentials are shared as a polished PDF via the device's native share sheet (WhatsApp/email). On first login the new admin hits ForceChangePassword before reaching their dashboard.

Bilingual & RTL

Arabic isn't a translation pass bolted on at the end — it's a structural requirement, and the layout has to mirror, not just relabel.

The engine in i18n.js is deliberately tiny: a key-based {en, ar} dictionary (~435 entries), a t() lookup that reads the current language at call time (no stale closures), and a useLang() hook so any component re-renders the instant the language flips. Switching also sets document.documentElement.dir to rtl, and index.css carries the mirrored layout rules.

RTL parity is where the real bugs lived. The CHANGELOG's nacc-23 fix is illustrative: an RTL sidebar-offset rule had higher specificity than the mobile reset, so on phones the entire Arabic admin got crammed into a ~250 px column while English was fine. The lesson — every RTL override must be scoped to the breakpoint where the element it compensates for actually exists. Menu option strings (sizes, extras) are translated on the fly via OPT_AR / translateNote, so a kitchen ticket reads correctly in either language.

Offline & Lebanon resilience

Slow Wi-Fi and power cuts are the operating environment, not the edge case. The caching strategy is shaped around that.

The service worker (public/sw.js) routes each request by what it is:

• App shell / HTML → network-first. Vite emits content-hashed bundles; serving stale index.html from cache pinned users to the previous bundle, so a deployed fix only took effect on the second load. Network-first means an online visitor always gets the latest, with cache fallback when truly offline.
• Menus & restaurants → stale-while-revalidate. These are large (inline base64 images) and rarely change, so they paint instantly from cache and refresh in the background. Writes to these tables purge their cached reads first, so the read right after an edit never serves the pre-write list.
• Live data (orders, sessions, logs) → network-first with a 3.5 s timeout. These are polled and must stay fresh; the timeout stops a connection that opens-but-never-responds from hanging the whole app.
• Fonts → cache-first (immutable).

Beyond caching, the Lebanon context drives product choices visible throughout: cash/card payment tracking with a card-toggle for cash-only venues, WhatsApp as the share channel for bills and credentials, and a static 0-ms splash so a slow first paint never shows a blank screen. A premium "local-LAN node" architecture for full offline operation has been scoped as a future tier.

Plans, billing & tenancy

The commercial layer is data, not branching logic scattered through the UI.

A single source of truth — PLAN_FEATURES in data.js — maps each tier to feature flags (ordering, table sessions, group ordering, kitchen access, order history, multi-QR print). Components call getPlanFeatures(restaurant.plan) rather than checking plan names inline, so a Basic menu-only restaurant simply has the cart and kitchen switched off, while Starter / Pro / Premium unlock the full system. Four tiers are defined with monthly prices and onboarding fees, plus yearly-discount math.

Master Admin's billing view computes MRR/ARR across all clients, flags overdue and due-soon accounts, records payments into a per-restaurant history, and can optionally mirror each payment to a Google Sheets webhook. Tenancy itself is enforced one level down — by RLS and the restaurant_id stamped server-side on every write — so the plan layer is purely about what features a paying tenant sees.

Developer Q&A

The questions a sharp engineer asks in the first hour. Answered straight — including where the answer is "that's known tech debt."

Appendix

Quick-reference catalogs for orientation.

Routes

RPC catalog (SECURITY DEFINER)

Environment variables

Glossary