kitchen-pos-blueprint
Build a production-grade restaurant POS (tabs, kitchen display, online and QR ordering, payments, terminals, offline mode, back office) as one multi-tenant codebase, then replicate it to other businesses (salons, clinics, gyms, retail) by configuration. Use when planning, building, testing or extending a POS, kitchen display system, ordering platform or a vertical SaaS family, and when you need the edge cases that break real money flows.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/ambergargrish-ca--kitchen-pos-blueprint)HTML
<a href="/listings/ambergargrish-ca--kitchen-pos-blueprint"><img src="/api/listings/ambergargrish-ca--kitchen-pos-blueprint/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
**Claude Code:** clone into your skills folder.
git clone https://github.com/ambergargrish-ca/kitchen-pos-blueprint ~/.claude/skills/kitchen-pos-blueprint
**Claude apps:** download the repo as a zip and upload it under Settings, Capabilities, Skills.
Then ask Claude things like "plan a POS for a three-branch cafe", "harden our tab payments against the edge cases", or "turn our restaurant POS into a salon product".
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 93 lines
- ---
- name: kitchen-pos-blueprint
- description: Build a production-grade restaurant POS (tabs, kitchen display, online and QR ordering, payments, terminals, offline mode, back office) as one multi-tenant codebase, then replicate it to other businesses (salons, clinics, gyms, retail) by configuration. Use when planning, building, testing or extending a POS, kitchen display system, ordering platform or a vertical SaaS family, and when you need the edge cases that break real money flows.
- license: MIT
- ---
- # Kitchen POS Blueprint
- A playbook for building a point-of-sale system a real restaurant can run a Friday night on, and then turning the same codebase into a family of products for other kinds of businesses.
- It is built from a working platform: one codebase serving restaurants in two countries plus salons, clinics, dental offices, gyms and shops, each its own deployment and brand. Every rule below exists because a real flow needed it.
- Stack used in the case study: Cloudflare Workers (Hono) + D1 (SQLite) + Durable Objects for live updates, plain HTML/JS front end, no build step. Every pattern is stack-neutral; see `references/01-architecture.md` for alternatives.
- ## The ten rules that matter most
- 1. **Money is integer cents. Always.** No floats anywhere: database, API, browser. Rates are basis points (1500 = 15.00%).
- 2. **The server prices everything.** The browser sends item ids, quantities and option ids. Prices, discounts, tax, tips, points and fees are recomputed on the server from the database on every request. Client totals are ignored.
- 3. **Every row carries `tenant_id` and every query filters on it.** Prove it with a second tenant in the test seed.
- 4. **Every state change that touches money is idempotent.** Webhooks, terminal results, offline replays, double taps, two tablets: each is applied once (idempotency keys, claimed-once rows, optimistic locks).
- 5. **Balances move only through atomic updates plus a ledger row.** Gift cards, loyalty points, deposits, tab `paid_cents`. Never read, add in code, write back.
- 6. **Read the payment result back from the provider** before marking anything paid. Redirects and browser callbacks prove nothing.
- 7. **Live money is off by default** and needs an explicit switch. Test keys are refused in live mode and live keys in test mode. Every mock and dev route dies in live mode.
- 8. **Modules are enforced on the server.** Hiding a button is never the only control.
- 9. **Time is the tenant's local wall clock,** stored as UTC epoch ms. Opening hours can pass midnight; DST happens.
- 10. **A vertical is configuration, not a fork.** One codebase, a `PRODUCT` and a `REGION` per deployment, words rewritten on the way out, modules filtered per product.
- ## Workflow
- ```
- 1 Scope -> 2 Model -> 3 Money core -> 4 POS + kitchen -> 5 Channels -> 6 Payments + devices
- -> 7 Offline + live -> 8 Back office -> 9 Harden (edge cases) -> 10 Go live -> 11 Replicate
- ```
- ### 1. Scope
- Write the module list first (see `references/01-architecture.md`, "Modules"). Decide per module: in the first release, later, or never. Name the roles (kitchen < staff < manager < owner, plus driver as a separate role). Decide the country and tax model before writing a single price.
- ### 2. Model the data
- Start from `templates/schema.sql`. Core tables: tenants, branches, staff_users, sessions, categories, menu_items (with modifiers JSON), orders, order_items, payments, refunds, kitchen_tickets, ledgers (points, gift cards), audit_log, webhook_events, idempotency. Read `references/02-data-model.md`.
- ### 3. Build the money core first, test it hardest
- Pricing, totals, tax (inclusive and exclusive), discounts, surcharges, tips, split bills, refunds and the daily journal. Pure functions, unit tested, before any screen exists. `scripts/money.js` is a reference implementation with `scripts/money.test.mjs`. Read `references/03-money.md`.
- ### 4. POS and kitchen
- Floor plan, tabs, rounds, seats, voids, moves, split payments, then the kitchen display with stations, bump, recall and timers. Read `references/04-pos-flows.md` and `references/05-kitchen-display.md`.
- ### 5. Channels
- Online ordering, QR table ordering (order now or pay at the end), kiosk, phone AI agent, delivery apps, and pushing orders into a POS the business already has. Every channel ends in the same order and ticket model. Read `references/07-channels.md`.
- ### 6. Payments and devices
- Hosted checkout (card data never touches you), signed webhooks, integrated terminals, surcharges, Connect-style payouts. Read `references/06-payments-devices.md`.
- ### 7. Offline mode and live updates
- A POS that stops when Wi-Fi drops is not a POS. Queue changes locally with idempotency keys and replay in order. Push changes to every screen over a WebSocket per tenant, with polling as a fallback. Read `references/04-pos-flows.md`, "Offline mode".
- ### 8. Back office
- Sales with tags, Z report, inventory with recipes, purchasing, timesheets, tips, payroll export, accounting journal (Xero/QuickBooks), audit log, insights. Read `references/03-money.md`, "Daily journal".
- ### 9. Harden against the edge cases
- Work through `references/edge-cases.md`. It is the core of this skill: 234 cases in 23 areas, each with what goes wrong and the rule that prevents it. Turn each into a test using `templates/edge-case-matrix.csv`. A release is not ready while any P0 row lacks a passing test.
- ### 10. Go live
- Run `templates/go-live-checklist.md`. Security review, live keys swapped deliberately, backups tested, provider certifications, privacy policy, support access rules.
- ### 11. Replicate to other businesses
- Read `references/09-replicate.md`. Map the new business onto the same primitives (items become services or products, tables become chairs or rooms, tickets become appointments), write a vertical profile from `templates/vertical-profile.json` (`python3 scripts/new_vertical.py <key>`), list what is genuinely new (appointments, memberships, insurer billing, age checks), and add only that. Then do the region pass in `references/10-regions-tax.md`.
- ## Testing tiers
- - **Quick (every change):** unit tests for the area you touched plus the edge-case rows tagged for it.
- - **Full (before each deploy batch):** all unit tests, then migrations + fresh seed + the end-to-end run against a local server, including the second-tenant isolation checks and every P0 edge case.
- - Detail in `references/11-testing-launch.md`.
- ## Reference map
- | File | Read when |
- |---|---|
- | `references/01-architecture.md` | Starting out; choosing stack, tenancy, modules, roles |
- | `references/02-data-model.md` | Designing tables, ids, statuses |
- | `references/03-money.md` | Anything with a price, tax, discount, tip, refund or report |
- | `references/04-pos-flows.md` | Tabs, floor, voids, splits, offline |
- | `references/05-kitchen-display.md` | Tickets, stations, routing, timers |
- | `references/06-payments-devices.md` | Checkout, webhooks, terminals, payouts, surcharges |
- | `references/07-channels.md` | Online, QR, kiosk, phone AI, delivery apps, POS integration |
- | `references/08-security-privacy.md` | Auth, PINs, roles, secrets, privacy law |
- | `references/09-replicate.md` | Turning the restaurant POS into other verticals |
- | `references/10-regions-tax.md` | A new country or province |
- | `references/11-testing-launch.md` | Test plan, CI, go-live |
- | `references/edge-cases.md` | Always, before calling any area done |
- ## Credit
- Created by Amber Gargrish ([gargrish.com](https://gargrish.com)). Built and proven on the Mainpoint platform (Platepoint for Canadian restaurants, Orbyt in New Zealand). If you use it, please cite it (see `CITATION.cff`).
README.md · README · 88 lines
- # kitchen-pos-blueprint
- A Claude skill for building a production-grade restaurant POS (tabs, kitchen display, online and QR ordering, payments, card terminals, offline mode, back office) as one multi-tenant codebase, and then replicating it to salons, clinics, dental offices, gyms and shops by configuration instead of forks.
- The core of the skill is an **edge-case catalog of 234 cases** across 23 areas, each with what goes wrong and the rule that prevents it, plus a CSV matrix and a gate script so no P0 case ships without a passing test.
- Built and proven on the Mainpoint platform: one codebase running restaurant POS brands in two countries (Platepoint in Canada, Orbyt in New Zealand) and products for salons, clinics, dental offices, gyms and stores.
- ## What it covers
- - **Architecture:** one codebase, one deployment per product and country, tenant isolation, switchable modules enforced on the server, roles
- - **Money core:** integer cents, server-side pricing, inclusive and exclusive tax, Ontario's $4 food rebate, discounts, surcharges, tips, split bills, refunds claimed once, a balanced daily journal
- - **POS:** floor and tabs, rounds, voids, moves, split payments, optimistic locks, close of day
- - **Offline mode:** IndexedDB queue, idempotency keys, ordered replay, what must never work offline
- - **Kitchen display:** stations, expo, recall, timers, order ahead, throttling, change tickets
- - **Channels:** online, branded websites, QR (pay first or pay at the end), kiosk, AI phone agent, delivery apps, pushing orders into a POS the business already has
- - **Payments and devices:** hosted checkout, webhook verification and replay protection, live-mode guards, Connect-style payouts, integrated terminals
- - **Security and privacy:** PIN peppering, trusted devices, CSRF, CSP, audit, support access, privacy law notes for NZ and Canada
- - **Replication:** primitive mapping per vertical, safe word rewriting, vertical profiles, what is genuinely new (appointments, memberships, insurer billing, age checks)
- - **Regions and tax:** NZ and every Canadian province, and a ten-point checklist for any new region
- ## Layout
- ```
- kitchen-pos-blueprint/
- ├── SKILL.md workflow and the ten rules (loaded first)
- ├── references/
- │ ├── 01-architecture.md
- │ ├── 02-data-model.md
- │ ├── 03-money.md
- │ ├── 04-pos-flows.md
- │ ├── 05-kitchen-display.md
- │ ├── 06-payments-devices.md
- │ ├── 07-channels.md
- │ ├── 08-security-privacy.md
- │ ├── 09-replicate.md
- │ ├── 10-regions-tax.md
- │ ├── 11-testing-launch.md
- │ └── edge-cases.md 234 cases, P0 / P1 / P2
- ├── scripts/
- │ ├── money.js reference money core (pure functions)
- │ ├── money.test.mjs node --test scripts/money.test.mjs
- │ ├── check_matrix.py edge-case gate for CI (--sync to add new ids)
- │ └── new_vertical.py scaffold a vertical profile
- └── templates/
- ├── schema.sql starter multi-tenant schema
- ├── vertical-profile.json words, modules, fields, rules per vertical
- ├── edge-case-matrix.csv every case id with test and status
- └── go-live-checklist.md
- ```
- ## Install
- **Claude Code:** clone into your skills folder.
- ```bash
- git clone https://github.com/ambergargrish-ca/kitchen-pos-blueprint ~/.claude/skills/kitchen-pos-blueprint
- ```
- **Claude apps:** download the repo as a zip and upload it under Settings, Capabilities, Skills.
- Then ask Claude things like "plan a POS for a three-branch cafe", "harden our tab payments against the edge cases", or "turn our restaurant POS into a salon product".
- ## Try the money core
- ```bash
- node --test scripts/money.test.mjs
- python3 scripts/check_matrix.py
- ```
- ## Companion skills
- - [zero-to-live](https://github.com/ambergargrish-ca/zero-to-live): plan, build, test in tiers, secure and deploy the web app
- - [brand-kit-builder](https://github.com/ambergargrish-ca/brand-kit-builder): brand each product in the family
- ## Not legal, tax or payments advice
- Tax rates, surcharge rules, gift card law and privacy notes reflect public rules as of November 2026. Check them with an accountant and a lawyer in each region before taking real money, and certify every payment integration with its provider.
- ## Citation
- If this skill helps your work, please cite it (`CITATION.cff`) or link back.
- Created by Amber Gargrish, [gargrish.com](https://gargrish.com).
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.