Restaurant POS Starter

1. What the system does

Restaurant POS Starter is a complete web application. Every device only needs a browser: a tablet or touch PC at the counter, a tablet in the hands of a waiter, a screen in the kitchen, a small screen facing the guest.

One installation serves any number of branches. Each branch has its own tax rate, service charge, prices, floor plan, terminals, stock and document numbers.

2. Install and start

You need

• Java 17 or newer (Java 21 recommended).
• Microsoft SQL Server 2019 or newer. The free Express edition is enough for a few branches.
• A modern browser (Chrome, Edge, Safari, Firefox) on each device.

Create the database

Open database/01-create-database.sql, change the password in it, and run it as a SQL Server administrator (SQL Server Management Studio, Azure Data Studio or sqlcmd):

sqlcmd -S localhost\SQLEXPRESS -E -i database\01-create-database.sql

It creates the database RestaurantPosDB with a UTF-8 collation and a login restaurant_pos. The application creates all tables itself on the first start (Flyway migrations).

Start

Set the connection and start the application (Windows example; on Linux or macOS use export and ./mvnw):

set DB_URL=jdbc:sqlserver://localhost;instanceName=SQLEXPRESS;databaseName=RestaurantPosDB;encrypt=true;trustServerCertificate=true
set DB_USERNAME=restaurant_pos
set DB_PASSWORD=the-password-you-chose
mvnw.cmd spring-boot:run

Or build once and run the jar: mvnw.cmd package then java -jar target\restaurant-pos-starter-1.0.0.jar. Open http://localhost:8080. On an empty database the demo data is created (about 20 seconds): two branches, a menu with recipes, stock, staff, members and two weeks of sales.

All settings are environment variables; env.example lists every one of them.

3. Demo accounts and PINs

Back-office password for every demo account: Demo@2026. Staff who work on terminals also have a PIN.

Two demo branches show both tax styles: Riverside adds 7% tax and a 10% service charge on dine-in; Old Town has prices that include tax and rounds cash to 0.05.

4. Set up a terminal

For security, staff sign in with a PIN only on devices that a manager has registered. A registered browser keeps a signed device cookie; another browser cannot use the PIN screen.

1. On the device, sign in to the back office as an admin or branch manager.
2. Open System > Terminals & stations and press Use this browser next to the terminal (POS1, KDS1...).
3. The device now shows the staff sign-in screen. The manager is signed out of the back office on that device.

The POS locks itself after 60 seconds without use (Settings). Press Lock to hand the device to a colleague; open bills stay as they are.

5. Open a shift

Payments are always booked into the shift of the terminal. The first cashier of the day opens the shift with the opening float (the change in the drawer). The Shift tab shows the payments taken, cash drops, cash in and the cash that should be in the drawer. Waiters can take orders without a shift; only taking payment needs one.

6. Take orders

• Dine-in: tap a free table and enter the number of guests.
• Take-away: counter or phone order with a name. Bills can be parked to serve the next guest.
• Quick sale: order and pay at once (coffee bar style).
• Drive-thru: car lane orders, with their own prices if you set them.

Tap an item to add it. Items with options (size, doneness, extras) open a choice dialog; required choices must be made. Add a note for the kitchen ("no peanuts"). Tap a line on the bill to change the quantity, add a note, give an item discount or void it.

The More menu of a bill: guests & name, move to another table, merge bills, split by items, send a held course, reopen a bill to add more, delivery status and void the whole bill. Add a member with their phone number or member number to earn and use points.

7. Send to the kitchen

Send prints a kitchen ticket per station (hot kitchen, cold, bar, pastry) and shows it on the kitchen display. Items can be held for a later course and sent with Send a held course. Unsent items are sent automatically when the bill is paid.

8. Take payment

Mix methods freely ("$20 cash, the rest by card"). Split equally shows each guest's share; Split by items (in More) moves items to a new bill. After payment the receipt prints and, if set, a QR code on it opens the e-receipt. A full tax invoice with the buyer's name, address and tax ID can be issued from a paid bill.

9. Approvals, voids and refunds

Some actions need a manager: voiding an item already sent to the kitchen, a discount above the cashier's limit, a credit sale, opening the drawer without a sale, a refund, and closing a shift with a large cash difference. The POS asks for the manager to tap their name and type their PIN on the same screen; the manager is recorded in the audit log.

• Void before sending: no approval, the item is simply removed.
• Void after sending: needs a reason and approval; the ingredients are booked as waste.
• Refund (Paid tab or Back office > Bills): whole bill or some items, by cash or the original method. A credit note with its own number is issued; the original receipt stays unchanged. Food that can be sold again goes back to stock.

10. Kitchen display

Register a kitchen screen as a KDS terminal and sign in with a kitchen PIN. Filter by station, press Start when cooking begins and Bump when the food is ready (the waiter sees "ready" on the floor plan). Recall brings back a ticket bumped by mistake. The kitchen can mark items sold out; every POS greys them out immediately.

11. Customer display

Each POS has a customer display link (System > Terminals > Customer display). Open it on a second screen facing the guest: it shows the items as they are added, the total and the payment QR code.

12. Close the shift and the day

In the Shift tab, count the cash by notes and coins. The system compares it with the expected cash and shows the difference. A difference above the limit needs a manager. Closing prints the Z report (sales by method, refunds, discounts, voids, cash movements), which is final and numbered. An X report can be printed at any time without closing. When all shifts of a branch are closed, a manager closes the business day (Back office > Shifts & end of day).

13. Back office: dashboard

The branch selector at the top switches between branches (for users allowed in several). The search box finds a bill by receipt or bill number. The theme button switches between light and dark.

14. Menu, prices and recipes

• Menu items: name, category, kitchen station, allergens, price per sales channel (dine-in, take-away, delivery, drive-thru) and per branch, a future start date for new prices, hours when the item is sold. Old bills keep the price they were sold at.
• Recipe: the ingredients of one portion, with waste percentage. Sub-recipes (sauces, doughs) are produced in the kitchen and used like ingredients.
• Options & extras: option groups (required or optional, minimum and maximum), with an extra price and extra ingredients.
• Combos: a set price with chosen items; stock is taken for each item.
• Sold out: items that cannot be ordered today; every POS and the kitchen see it at once.
• Floor plan: zones and tables with shape, seats and position.

15. Stock

Every paid bill takes its ingredients from stock automatically (recipe × quantity, plus options). Cost is calculated first in, first out: the oldest received goods are used first, so food cost is exact even when prices change.

• Movements: every change of stock, with who, when and why. Movements are never edited or deleted; a mistake is corrected with a new movement.
• Counts: count the stock, compare with the system, approve the differences.
• Waste: spoiled, expired or dropped goods with a reason.
• Transfers between branches and production of sub-recipes.
• Units: buy by case, count by bottle, use by millilitre; conversions are set per ingredient.

16. Purchasing

1. A purchaser creates a purchase order for a vendor (it can be suggested from the reorder levels).
2. A manager approves it.
3. When goods arrive, Receive goods records the quantities, prices, lot numbers and expiry dates. A price above the ordered price by more than the set percentage needs approval. Stock and FIFO cost are updated at once.

17. Members, points and promotions

• Members earn points per amount spent (more in their birthday month); points expire after the set months.
• Members agree to the privacy notice when they join. A member can ask for their data (export) or to be forgotten (anonymize).
• Promotions: percent or amount off, by item, category or bill, by day and time, for members only, with a minimum spend.
• Coupons: single-use codes with a value and validity, issued in batches.

18. Delivery orders

Orders from delivery platforms arrive by webhook (see docs/API.md). Each platform has its own signing secret, commission rate and menu map (their item codes to your items). An order with unknown items goes to the exceptions list instead of being lost. The demo has two fictional platforms; Simulate sends a test order.

19. Reports

Also: food cost, voids & discounts by staff (the control report) and delivery by platform. Reports can show one branch or all.

20. Tax and accounting

• Receipts are numbered per branch and year without gaps. A sale that fails gives its number back.
• Full tax invoices and credit notes have their own numbers and can be sent to an e-invoice service (a test service is included; replace ETaxProvider with your provider).
• VAT report (CSV) and a daily journal file for your accounting system (CSV, written at 03:00 to the export folder, or exported on demand).
• Failed sends are retried and then shown in Exceptions with a Retry button.

21. Users, roles and security

Each user can be limited to some branches and given their own discount limit. Back-office users can switch on two-step sign-in with an authenticator app (Profile). Passwords need at least 8 characters with upper and lower case, a digit and a symbol; PINs cannot be simple runs like 1234 or 1111.

22. Settings

System > Settings (system admin):

Per branch (System > Branches): legal name, tax ID, address, tax rate, prices with or without tax, service charge, cash rounding, the time a business day starts and the receipt header and footer.

23. Rules the system always keeps

These rules are enforced by the database itself, so not even a bug or a direct SQL change can break them:

• A paid bill, its items and payments cannot be changed or deleted (only the kitchen progress may still be updated).
• Stock movements, point transactions, cash movements and the audit log are append-only.
• The total of a bill must equal its parts; card data holds only 4 digits; only cash gives change.
• A table has at most one open bill; a terminal has at most one open shift; receipt numbers are unique.

The test suite checks these on a real SQL Server, including 2,000 receipt numbers taken in parallel with failed sales in between (no gaps, no duplicates).

24. Going live

1. Create a new empty database, set SEED_DEMO_DATA=false and ADMIN_INITIAL_PASSWORD.
2. Set new secrets: APP_DATA_KEY (openssl rand -base64 32), APP_DEVICE_SECRET, PAYMENT_WEBHOOK_SECRET. Keep APP_DATA_KEY safe: without it encrypted member data cannot be read.
3. Run behind HTTPS (a reverse proxy such as nginx, IIS or Caddy) and set SESSION_COOKIE_SECURE=true and APP_BASE_URL.
4. Set CURRENCY_SYMBOL, CURRENCY_CODE and APP_TIME_ZONE; enter your branches, tax rates and menu.
5. Connect your QR payment and e-invoice providers (implement QrPaymentGateway / ETaxProvider) and a mail server for e-receipts.
6. Back up the database every day and test a restore.

Step-by-step server notes are in docs/DEPLOY.md.

25. Troubleshooting