# User Guide — Restaurant Manager Workbook (version 7.0.0) This guide is for a restaurant owner, not a developer. It explains, in plain English, how to use the workbook day to day. The workbook is one HTML file. It runs entirely in your browser, works offline, and needs no account. Your data stays on your device unless you choose to export or share it. > **A note on the demo data.** The workbook opens with a demo business and > sample data, so you can try everything safely. Every figure in this guide > that comes from that demo (for example, an invoice total of 84.53) is > **demo data only** — it is not a real business record. ## Contents - [Start here](#start-here) - [The demo business](#the-demo-business) - [Setup wizard — your own business](#setup-wizard--your-own-business) - [Stock](#stock) - [Recipes](#recipes) - [Production](#production) - [Sales and invoices](#sales-and-invoices) - [Cash, cash-up and Z-report](#cash-cash-up-and-z-report) - [Bank reconcile](#bank-reconcile) - [Salaries](#salaries) - [Dashboard and Controls](#dashboard-and-controls) - [ZATCA — Phase 1 QR and Phase 2 providers](#zatca--phase-1-qr-and-phase-2-providers) - [Food safety](#food-safety) - [Backups](#backups) - [PINs and roles](#pins-and-roles) - [Updating to a newer version](#updating-to-a-newer-version) - [If something goes wrong](#if-something-goes-wrong) ## Start here **Open the file.** Double-click the downloaded `.html` file, or open `app.html` in your browser. No install is needed. **Look around first.** The menu on the left has 19 sections, grouped as Overview, Sell, Kitchen & stock, Money, People and Setup. Start with the **Dashboard** to see the shape of the business, then open **Sales & Invoices** and **Stock**. **Try the demo before your own data.** Everything in the demo is safe to change, delete or break — it is sample data, and you can reload it from Settings. Only start the setup wizard when you are ready to enter your real business. ## The demo business The demo is a small restaurant in Jeddah with 7 employees, 43 stock items, 12 invoices and 7 salary rows (demo data). It exists so you can: - issue an invoice and see the bilingual layout and QR code; - run a cash-up and a Z-report; - run a salary month and see a payslip; - see what the Dashboard and the 36 Controls checks look like with real numbers in them. The demo banner at the top of the screen says it is sample data and offers **Set up a new business**. You can dismiss the banner; the setting is kept in your browser, not in the workbook data. Two honest notes about the demo: - The demo sells more of two pizza sizes than the kitchen produced. That is a mistake in the sample data, left as-is on purpose. If you try to sell those on the demo, the workbook correctly refuses until you produce them first. That refusal is the app working properly. - Demo figures are used in testing to prove nothing broke. For example, the demo's employee E001 October net pay is 9,096.87 and invoice INV-00001 totals 84.53. Those are test anchors, not real money. ## Setup wizard — your own business Open **Set up a new business** from the demo banner, or start the wizard from Settings. The wizard has 15 steps: 1. **Business** — restaurant name (English and Arabic), VAT number (15 digits, starts and ends with 3), commercial registration number, address, phone. 2. **Employees** — add your staff, with nationality and GOSI details. 3. **Ingredients** — your raw materials, with a base unit (g, ml, pcs) and a purchase unit (kg, bag, box). 4. **Stock on hand** — opening quantities and costs. 5. **Recipes** — your dishes, with ingredients and yield. 6. **Suppliers & overheads** — suppliers with payment terms, and regular costs such as rent. 7. **Goods Received** — deliveries already received. 8. **Stock review** — check the opening stock before you continue. 9. **Production** — what the kitchen has cooked. 10. **Invoices** — any open invoices. 11. **Cash & Bank** — tills and bank accounts, with opening balances. 12. **Salaries** — salary rows, if any. 13. **Dashboard & Controls** — a first look at the reports. 14. **Choose where your data lives** — pick a backup folder on your device (optional; the workbook also saves automatically in the browser). 15. **Export & ready** — export your first backup file. **The wizard will not finish until you have a backup.** The export step must actually succeed — cancelling the download does not count. Keep that backup file somewhere safe, away from the computer you use every day. Every dropdown in the wizard has **"+ Add new…"**, so you can add a supplier, item or list value while you work instead of stopping to set it up first. ## Stock **Items** (Kitchen & stock → Stock) is your list of raw materials. Each item has: - a **base unit** (g, ml, pcs) — the unit recipes use; - a **purchase unit** (kg, bag, box) and how many base units it holds; - an **opening quantity and cost**, which start the stock; - a **reorder level** — when stock falls to this level, the workbook warns you; - a **storage type** (Chilled, Frozen, Ambient) and an expiry date where it matters. **Costs are weighted-average.** When you buy the same item at a new price, the workbook blends the old and new cost into one average cost. That average is what recipes and profit use. You do not need to calculate it. **Goods Received** records a delivery: date, supplier, item, quantity, cost, VAT. It adds to stock and keeps the supplier's price history. **Stock adjustments** record anything else that changes stock: spoilage, wastage, staff meals, complimentary food, loss, or a stock count that finds more or less than the books say. **Archive** items you stop using instead of deleting them — they keep their history, and old recipes and reports still work. ## Recipes A recipe lists the ingredients for one batch, how many portions the batch makes (the **yield**), and the selling price. The workbook works out the cost per portion from the current average cost of each ingredient, and shows the margin. - **Prep recipes** are recipes used inside other recipes (for example, a sauce made in the kitchen and used in several dishes). Change the prep recipe once and every dish that uses it updates. - **Size variants** are the same dish in different sizes, each with its own price and ingredient quantities. - **Forecast portions per day** is your guess at how many portions you sell in a day. It feeds the forecast and the stock alerts. ## Production Production records what the kitchen actually cooked: date, recipe, number of batches. Sales then check against **cooked portions on hand** (produced minus sold). If you try to sell more than was cooked, the workbook refuses the shortfall and tells you to produce first. Only the shortfall is refused — if you produced 5 and sell 5, that is fine. ## Sales and invoices ### Issuing an invoice Open **Sales & Invoices**, add lines from your recipes, and issue the invoice. The invoice is bilingual (English and Arabic) and carries: - your business name, VAT number and CR number; - the date and time of issue; - the lines, VAT breakdown (15%) and total; - a **ZATCA Phase 1 QR code** (see the ZATCA section below); - a unique invoice number and a UUID. **Once issued, an invoice is frozen.** Its numbers never change, even if you later change a recipe price or an ingredient cost. That is deliberate: the invoice is the record of what was actually charged. Profit reports use the frozen cost; the Controls check uses today's average cost, and the two can differ — both screens say so plainly. ### Split payments One invoice can be paid in parts, in different ways — for example, part cash and part card. Payment methods are generic categories only: Cash, National debit card network, International card networks, Mobile wallet payments, Bank Transfer, Delivery apps, Government e-payment system. ### Credit notes A credit note cancels or partly cancels an issued invoice. It has its own number, refers to the original invoice, and uses type 381 in the Phase 2 XML. To void an invoice in the books, issue a credit note — do not delete the invoice. ### Sharing and printing From the invoice view you can print, download a PDF, share the PDF, or download a thermal receipt text file (for a receipt printer — you send the file to the printer yourself). If a document ever renders blank, the workbook now stops and tells you to use **Print → Save as PDF** instead of sharing a blank file. ### Held orders You can hold an order and come back to it later. Held orders do not change stock or sales until they are invoiced. ## Cash, cash-up and Z-report **Cash** holds your tills, bank accounts and delivery-app receivable accounts. - **Cash-up (daily close):** count the cash in the till at the end of the day and enter it. The workbook shows what it expected, and the difference (the variance). A cash-up is the record — do the count, enter the real number, do not adjust it to match. - **Z-report:** the end-of-day summary for a till — sales, VAT, payment breakdown and cash expected. Print it or download it as a PDF or a thermal receipt file. - **Shift sessions:** if you run shifts, open a shift for a till with an opening float, run a mid-shift **X-report** (sales and expected cash so far, without closing), and close the shift — closing runs the ordinary cash-up and records the variance. With no shift open, the plain daily cash-up works exactly as before. - **Money in / money out:** record cash movements that are not sales, such as paying a supplier in cash or putting in extra float. ## Bank reconcile Open **Cash → Reconcile** to match your bank statement against the workbook. 1. Import or enter the bank statement lines (date, description, reference, debit, credit, balance). 2. The workbook matches statement lines to invoices and receipts. For payout statements from delivery apps, matching is **by invoice reference only, never by amount** — two lines with the same amount are never treated as the same payment. 3. A line is shown as matched, unmatched or ambiguous. Importing posts nothing by itself. When you post a matched line, it settles the invoice through the normal paired legs, capped at the amount owed — it cannot overpay an invoice. 4. Duplicate references are marked ambiguous from the second line on. Credit-note references are shown for review only and cannot be posted; refunds are handled in Sales → Credit notes. **Migration note:** if money from a delivery app was already moved with the old manual transfer (receivable → bank), do **not** also settle the same invoice with the new action — that would count it as paid twice. Delete the old transfer and settle with the new action instead. ## Salaries **Employees** holds each person's details: name, nationality, basic salary, allowances, GOSI details and leaving date if they left. Nationality feeds the Nitaqat ratio (see below). **Attendance** records daily attendance and overtime hours. **Salary** runs the monthly pay: - **Overtime** follows Saudi Labour Law article 107 (the default basis; change it in Settings → Payroll only if you know what you are doing). - **GOSI fields** are recorded per employee. **Please confirm the current phased GOSI rates with GOSI before you use the workbook for real payslips** — the rates in the workbook may not be the latest. - **Ramadan mode** (Settings → Payroll, off by default): when on, Sales gains iftar pre-orders and a suhoor/iftar prep forecast. The 6-hour Ramadan working day and the Ramadan overtime cap apply on the Ramadan dates whether the toggle is on or off — the toggle only switches the pre-order and forecast sections. **Ramadan 2027 dates in the workbook are expected, not official** — check the official announcement. - A **paid payslip is frozen** like an invoice: its numbers never change after payment. - **Payslips** can be printed or shared as PDF. **Nitaqat ratio** is shown in the Employees section from nationality and headcount, with a warning below the level (default 20%, editable in Settings → Payroll). In the demo business it is 1 Saudi of 7 staff, 14.29%, so the warning shows. The bands are estimates — confirm them with the relevant authority. The ratio never blocks payroll. ## Dashboard and Controls **Dashboard** is the first screen: sales, profit and loss, forecast, break-even, VAT summary and a zakat estimate. It also shows an **Attention** summary — for example, the demo shows a count of errors and warnings — so you can see at a glance what needs you. **Controls** runs 36 automatic checks across the whole workbook and lists every problem it finds, naming the record to fix: a missing VAT number, an invoice without a QR code, a stock item below reorder level, a cash-up variance, a queued e-invoice submission, and more. Work through the list top to bottom. **Forecast** predicts sales by recipe from past sales and your forecast portions per day. With Ramadan mode on, it also shows an expected portions-per-day forecast by daypart (suhoor / iftar). Every forecast is labelled as a forecast — it is a planning aid, not a promise. **Zakat estimate** (Dashboard, after the VAT section; hidden from Cashiers) is equity + long-term liabilities − fixed assets at 2.5%, from the workbook's own figures. In the demo it is a base of 6,280.91 and zakat of 157.02 (demo data). It is labelled **"Estimate only — not a filing. Confirm with your accountant."** If an input is missing, it names what is missing instead of inventing a number. ## ZATCA — Phase 1 QR and Phase 2 providers ### Phase 1 — what every invoice already has Every issued invoice carries a **ZATCA Phase 1 QR code** (TLV format, base64). The QR holds the seller name, VAT number, invoice date and time, total including VAT, and VAT amount. It is generated offline, from the frozen invoice. Each invoice also has a UUID and a hash chained to the previous invoice, so the sequence can be checked. Phase 1 is complete in the workbook. Nothing more is needed for it. ### Phase 2 — what the workbook prepares, and what a provider does The workbook **prepares** e-invoices offline: it builds a simplified UBL 2.1 XML from the frozen invoice, checks it offline for shape and required fields, and keeps a submission status per invoice. **It never sends anything to the tax authority.** The workbook makes no network calls at all. Live submission (clearance) needs a **ZATCA-approved e-invoicing provider of your choice**. The provider is the company that takes the ready XML, checks it, and sends it to the tax authority. To connect one: 1. Go to **Settings → E-invoicing**. 2. Add the provider: name, base URL, submission endpoint, status endpoint, login type (API key, OAuth 2.0, Basic auth, or certificate), and a short label saying which credential to use. 3. **Never type a secret key into the workbook.** The credential label is a label only — the secret stays with the provider or in your password manager. The workbook rejects anything that looks like a pasted secret. 4. Set the provider as active. "Manual / offline" is the default and means nothing is sent. Submission statuses are: Not submitted, Queued, Submitted, Accepted, Rejected, Failed, Cancelled. **Only Accepted — with a submission reference — counts as cleared.** A provider that cannot be reached leaves the invoice **Queued ("not submitted")** with a Retry button; it is never silently marked cleared. The Controls check `zatcaReady` flags any invoice that is queued, failed or rejected, and any gap in the Phase 1 fields, the XML or the hash chain. **Honest limits:** the XML is a simplified UBL 2.1 invoice, not certified ZATCA XML — full clearance compliance is the provider's check. A vendor who wants to plug in should read [docs/ZATCA.md](ZATCA.md) and the Guide section "E-invoicing providers — what a provider must implement" inside the app. ## Food safety Food safety is behind a toggle in the Daily close area. When on: - **Temperature logs** for fridge (0–5 °C) and freezer (−18 °C or colder), with an alert when a reading is out of range. These ranges are common guidance — confirm them locally. - **Opening and closing checklists** (5 items each) for the daily close. - **Inspection pack** — a printable pack (temperatures, checklists, VAT/CR, licences, cleaning and pest-control costs, stock-expiry notes) for a municipal inspection. Nothing in food safety blocks sales or invoices. ## Backups Your data is saved automatically in the browser as you work. Automatic saving is **not** a backup — if the browser data is cleared, it is gone. Keep real backups: - **Export data (JSON):** Settings → Export data. Save the `.json` file somewhere safe — a different device, a USB stick, or cloud storage you control. Do this at least weekly, and always before updating the workbook. - **Backup folder:** Settings lets you pick a folder on your device where the workbook writes a backup file automatically. If the first write fails, the workbook now says so instead of claiming success. - **Export to Excel:** the workbook can export all tables as an Excel file (28 sheets). This is a report and a second copy of your data, not a full backup — import back from the JSON file, not from Excel. - **Exported app (.html):** you can export a copy of the workbook file with your data inside it. Keep it as a spare copy. **If the browser data is cleared** (or you move to a new computer), open the workbook file and import your latest `.json` backup. That is the whole recovery. ## PINs and roles **Roles** control what each person can see and do: - **Owner** — everything, including Settings → Security. - **Manager** — day-to-day work, but not security settings. - **Cashier** — sales and cash only; salary figures and some reports are hidden. **Master password.** Set one in Settings → Security. It locks the salary data and encrypts exported files. Keep it somewhere safe — if you lose it, encrypted exports cannot be opened. **Per-person PINs** (4–6 digits, set by the Owner in Settings → Security) let each person sign in quickly. A PIN is a **convenience sign-in only**: it never replaces the master password, and it never unlocks a locked module. If a Manager signs in with a PIN while the salary module is locked, the salary screen stays locked. The audit log records the person (name and ID), not just the role. **Honest limit:** browser autosave and snapshots are **not encrypted** — only exported files are. Anyone with access to the device and the browser could read the saved data. Lock the device itself, and do not treat a PIN as security against someone who has the device. ## Updating to a newer version A backup file (`.json`) exported by any older version loads in any newer version. To update: 1. In the old file: **Settings → Export data** and save the `.json` file. 2. Download the new workbook file (or open the new online version). 3. In the new file: **Settings → Import data** and choose the `.json` file. 4. Check the Dashboard and Controls. The app reports any upgrade it made (for example, "Upgraded data from schema v1 to v2"). Older files always load. New fields get sensible defaults. Old payment-method names are renamed to the current generic categories. Nothing is silently deleted. A file from a *newer* version loads what it can and warns about the rest. See [docs/DATA-FORMAT.md](DATA-FORMAT.md). ## If something goes wrong - **"Another tab saved newer data"** — you have the workbook open in two tabs or windows. Close one, reload the other, and keep working in one tab only. The warning can linger until you reload; the guard itself is already working. - **A share or download gives a blank file** — use **Print → Save as PDF** instead, and report the problem. The workbook now checks for blank documents and stops instead of sharing one. - **A backup or export claims success but nothing arrived** — check your downloads folder and your browser's pop-up blocker. The workbook now only claims success when the export really happened. - **The app shows "Something went wrong"** — reload the page. Your data is saved automatically, so you should lose nothing. If it keeps happening, import your latest `.json` backup into a fresh copy of the file. - **You forgot the master password** — encrypted exports cannot be opened without it. The data still in the browser is unaffected, so export a new backup (you will be asked for the password only for the export) — if you cannot supply it, the export will be refused rather than saved unprotected. Keep the password somewhere safe in future.