Skip to content
Back to search

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ambergargrish-ca--kitchen-pos-blueprint/badge.svg)](/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

i

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
  1. ---
  2. name: kitchen-pos-blueprint
  3. 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.
  4. license: MIT
  5. ---
  6. # Kitchen POS Blueprint
  7. 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.
  8. 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.
  9. 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.
  10. ## The ten rules that matter most
  11. 1. **Money is integer cents. Always.** No floats anywhere: database, API, browser. Rates are basis points (1500 = 15.00%).
  12. 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.
  13. 3. **Every row carries `tenant_id` and every query filters on it.** Prove it with a second tenant in the test seed.
  14. 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).
  15. 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.
  16. 6. **Read the payment result back from the provider** before marking anything paid. Redirects and browser callbacks prove nothing.
  17. 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.
  18. 8. **Modules are enforced on the server.** Hiding a button is never the only control.
  19. 9. **Time is the tenant's local wall clock,** stored as UTC epoch ms. Opening hours can pass midnight; DST happens.
  20. 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.
  21. ## Workflow
  22. ```
  23. 1 Scope -> 2 Model -> 3 Money core -> 4 POS + kitchen -> 5 Channels -> 6 Payments + devices
  24. -> 7 Offline + live -> 8 Back office -> 9 Harden (edge cases) -> 10 Go live -> 11 Replicate
  25. ```
  26. ### 1. Scope
  27. 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.
  28. ### 2. Model the data
  29. 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`.
  30. ### 3. Build the money core first, test it hardest
  31. 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`.
  32. ### 4. POS and kitchen
  33. 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`.
  34. ### 5. Channels
  35. 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`.
  36. ### 6. Payments and devices
  37. Hosted checkout (card data never touches you), signed webhooks, integrated terminals, surcharges, Connect-style payouts. Read `references/06-payments-devices.md`.
  38. ### 7. Offline mode and live updates
  39. 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".
  40. ### 8. Back office
  41. 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".
  42. ### 9. Harden against the edge cases
  43. 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.
  44. ### 10. Go live
  45. Run `templates/go-live-checklist.md`. Security review, live keys swapped deliberately, backups tested, provider certifications, privacy policy, support access rules.
  46. ### 11. Replicate to other businesses
  47. 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`.
  48. ## Testing tiers
  49. - **Quick (every change):** unit tests for the area you touched plus the edge-case rows tagged for it.
  50. - **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.
  51. - Detail in `references/11-testing-launch.md`.
  52. ## Reference map
  53. | File | Read when |
  54. |---|---|
  55. | `references/01-architecture.md` | Starting out; choosing stack, tenancy, modules, roles |
  56. | `references/02-data-model.md` | Designing tables, ids, statuses |
  57. | `references/03-money.md` | Anything with a price, tax, discount, tip, refund or report |
  58. | `references/04-pos-flows.md` | Tabs, floor, voids, splits, offline |
  59. | `references/05-kitchen-display.md` | Tickets, stations, routing, timers |
  60. | `references/06-payments-devices.md` | Checkout, webhooks, terminals, payouts, surcharges |
  61. | `references/07-channels.md` | Online, QR, kiosk, phone AI, delivery apps, POS integration |
  62. | `references/08-security-privacy.md` | Auth, PINs, roles, secrets, privacy law |
  63. | `references/09-replicate.md` | Turning the restaurant POS into other verticals |
  64. | `references/10-regions-tax.md` | A new country or province |
  65. | `references/11-testing-launch.md` | Test plan, CI, go-live |
  66. | `references/edge-cases.md` | Always, before calling any area done |
  67. ## Credit
  68. 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
  1. # kitchen-pos-blueprint
  2. 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.
  3. 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.
  4. 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.
  5. ## What it covers
  6. - **Architecture:** one codebase, one deployment per product and country, tenant isolation, switchable modules enforced on the server, roles
  7. - **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
  8. - **POS:** floor and tabs, rounds, voids, moves, split payments, optimistic locks, close of day
  9. - **Offline mode:** IndexedDB queue, idempotency keys, ordered replay, what must never work offline
  10. - **Kitchen display:** stations, expo, recall, timers, order ahead, throttling, change tickets
  11. - **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
  12. - **Payments and devices:** hosted checkout, webhook verification and replay protection, live-mode guards, Connect-style payouts, integrated terminals
  13. - **Security and privacy:** PIN peppering, trusted devices, CSRF, CSP, audit, support access, privacy law notes for NZ and Canada
  14. - **Replication:** primitive mapping per vertical, safe word rewriting, vertical profiles, what is genuinely new (appointments, memberships, insurer billing, age checks)
  15. - **Regions and tax:** NZ and every Canadian province, and a ten-point checklist for any new region
  16. ## Layout
  17. ```
  18. kitchen-pos-blueprint/
  19. ├── SKILL.md workflow and the ten rules (loaded first)
  20. ├── references/
  21. │ ├── 01-architecture.md
  22. │ ├── 02-data-model.md
  23. │ ├── 03-money.md
  24. │ ├── 04-pos-flows.md
  25. │ ├── 05-kitchen-display.md
  26. │ ├── 06-payments-devices.md
  27. │ ├── 07-channels.md
  28. │ ├── 08-security-privacy.md
  29. │ ├── 09-replicate.md
  30. │ ├── 10-regions-tax.md
  31. │ ├── 11-testing-launch.md
  32. │ └── edge-cases.md 234 cases, P0 / P1 / P2
  33. ├── scripts/
  34. │ ├── money.js reference money core (pure functions)
  35. │ ├── money.test.mjs node --test scripts/money.test.mjs
  36. │ ├── check_matrix.py edge-case gate for CI (--sync to add new ids)
  37. │ └── new_vertical.py scaffold a vertical profile
  38. └── templates/
  39. ├── schema.sql starter multi-tenant schema
  40. ├── vertical-profile.json words, modules, fields, rules per vertical
  41. ├── edge-case-matrix.csv every case id with test and status
  42. └── go-live-checklist.md
  43. ```
  44. ## Install
  45. **Claude Code:** clone into your skills folder.
  46. ```bash
  47. git clone https://github.com/ambergargrish-ca/kitchen-pos-blueprint ~/.claude/skills/kitchen-pos-blueprint
  48. ```
  49. **Claude apps:** download the repo as a zip and upload it under Settings, Capabilities, Skills.
  50. 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".
  51. ## Try the money core
  52. ```bash
  53. node --test scripts/money.test.mjs
  54. python3 scripts/check_matrix.py
  55. ```
  56. ## Companion skills
  57. - [zero-to-live](https://github.com/ambergargrish-ca/zero-to-live): plan, build, test in tiers, secure and deploy the web app
  58. - [brand-kit-builder](https://github.com/ambergargrish-ca/brand-kit-builder): brand each product in the family
  59. ## Not legal, tax or payments advice
  60. 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.
  61. ## Citation
  62. If this skill helps your work, please cite it (`CITATION.cff`) or link back.
  63. Created by Amber Gargrish, [gargrish.com](https://gargrish.com).
  64. ## License
  65. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.