vertical-restaurants

name	vertical-restaurants
description	Domain-knowledge primer for the restaurants & hospitality vertical (dine-in, pickup, delivery). Gives architect and pm the vocabulary, non-obvious operating rules, must-model entities, and incumbent landscape so a restaurant-product spec isn't naive about modifiers, 86'd items, aggregator commissions, tip law, and razor-thin margins. Covers the 4 products: online-ordering, reservations, loyalty, shift-scheduling.
when_to_use	Apply when speccing a restaurant / hospitality product: - architect writing ARCH-*.md for online-ordering, reservations, loyalty, or shift-scheduling - pm decomposing a restaurant feature and sizing tasks - anyone modelling a menu, order, booking, or rota and at risk of a flat/naive data model Do NOT apply for generic booking/CRM/content products outside food & hospitality.
effort	low
allowed-tools	Read, Write, Grep, Glob
paths	["docs/architecture/**","docs/plans/**","docs/design/**"]

Vertical: restaurants & hospitality — don't spec it naive

Restaurants run on razor-thin margins (net 3–6%) with a hostile incumbent stack. A spec that treats a menu as a flat list of {name, price} or ignores who already owns the POS will ship something no operator can use. This skill loads the domain so architect/pm sound like they've worked a shift.

The 4 products in this vertical:

Product	Archetype	One-liner
online-ordering	content	Own menu + checkout for dine-in/pickup/delivery — dodge aggregator fees
reservations	booking	Bookings, tables, text-the-waitlist
loyalty	crm	Points, offers, win-back
shift-scheduling	booking	Rota, open shifts, swaps with coverage rules

Incumbents to position against: Toast (POS, ~$69–165/mo + hardware + 2.49%+ per swipe), Square (POS/SMB), SevenRooms (reservations/CRM, upmarket), ChowNow (commission-free ordering), DoorDash / Uber Eats / Grubhub (aggregators, 15–30% commission per order).

1. Domain vocabulary (use these words in the spec)

• COGS / food cost % — cost of ingredients ÷ menu price. Target ~28–35%.
• Prime cost — food cost + labor cost; the number operators obsess over (target ≤ ~60% of sales).
• Menu engineering — classifying items by popularity × margin into stars (high/high), plowhorses, puzzles, dogs (low/low). Drives what gets promoted or cut.
• 86'd — an item is out of stock / unavailable ("we're 86 on the salmon"). Must propagate instantly to every ordering channel.
• Modifiers / mods — choices on an item (size, temp, add bacon, no onions, sub fries). Grouped, with required/optional + min/max rules.
• Covers — number of guests served (a "200-cover night").
• Turn time — how long a table is occupied; reservations math depends on it (a 2-top turns in ~75 min).
• FOH / BOH — front of house (servers, host, bar) / back of house (kitchen, prep, dish). Scheduling and tips differ between them.
• Tip pooling — pooled tips split by rule (hours, role, points). Legally constrained — see §6.
• Comps / voids — comp = item given free (manager discretion); void = item removed before it's made. Both need audit trails.
• Ticket times — elapsed time from order fired to served; the kitchen's core SLA.
• Third-party aggregator commission — the 15–30% DoorDash/Uber Eats/ Grubhub take. The pain that makes owned ordering a wedge.
• KDS (kitchen display system) — screen in the kitchen that replaces paper tickets; orders route to it by station.

2. Non-obvious domain rules

• The POS is the sticky system of record — don't fight it. Toast/Square own the menu, payments, and floor. Our products integrate with or sit beside the POS; they don't try to replace it. Sync the menu, don't fork it.
• Aggregator commission is the wound; owned online-ordering is the wedge. A restaurant paying 25% to DoorDash on a $40 order keeps $30. Commission- free direct ordering is the single clearest ROI pitch — lead with it.
• Menus have deep modifier hierarchies, not flat prices. "Burger" → size group (required, choose 1) → temp group (required) → add-ons (optional, 0–5) → side (required, choose 1, sub upcharges). Price = base + mods.
• 86'd / out-of-stock is real-time and must sync everywhere. When the kitchen 86's an item it must vanish from online ordering, KDS, and the POS simultaneously, or you sell what you can't make.
• Tips have legal handling. Pooling rules, who can share (FLSA bars managers/owners from tip pools), tip credit, and service-charge vs tip distinction are labor-law constrained, not free-form.
• Margins are razor-thin. A feature that adds 30¢/order of cost can erase the margin on that order. Cost-consciousness is a feature, not a nicety.
• Reservations + waitlist are SMS-driven. "Your table's ready" is a text, not an email. Waitlist quote times and ready-pings are the product.

3. What a naive build gets wrong

• Flat menu, no modifier hierarchy. {name, price} can't express "medium, well-done, add bacon, sub fries (+$2)". Model modifier groups with required/optional + min/max from day one.
• Ignoring 86'd / out-of-stock. Selling a sold-out item online is a refund, an angry guest, and a chargeback. Stock state is first-class.
• Online ordering that doesn't sync the menu. A second menu that drifts from the POS menu means wrong prices and phantom items. One source of truth, synced.
• Tip handling that breaks labor law. Letting managers into the pool, or mislabeling a service charge as a tip, is an FLSA violation, not a bug.
• No dine-in vs pickup vs delivery distinction. Each channel has different fulfillment, timing, fees, address/table data, and tax. One generic "order" type is wrong.
• Loyalty that's points-only with no win-back. Points without a lapsed- guest re-engagement flow (offers, "we miss you") leaves the highest-ROI CRM lever on the table.

4. Must-model entities

• MenuItem — base price, category, station, tax class, availability state (available / 86'd / scheduled), with one or more ModifierGroups.
• ModifierGroup — {required: bool, min, max} + ordered Modifiers (name, price delta, default, in-stock). Hierarchy, not a flat list.
• Order — channel (dine_in | pickup | delivery), status (placed → confirmed → preparing → ready → completed | cancelled), line items with resolved modifiers, computed total, table/address per channel.
• Reservation — party size, time, turn-time estimate, table assignment, status; plus Waitlist entry (quoted wait, ready-ping, SMS thread).
• Shift — role (FOH/BOH), start/end, coverage rule (min staff per role/time), open shift + swap request with approval/coverage check.
• LoyaltyMember — identity (phone-first), points balance, earn/redeem ledger, last-visit (for win-back segmentation), consent state.

5. Per-product notes (wedge + the one domain thing)

• online-ordering (content) — Wedge: commission-free direct ordering vs DoorDash's 15–30% and Toast Online Ordering's per-order fee. The one thing: the menu + modifier hierarchy must sync from the POS and honor 86'd state, across dine-in/pickup/delivery, or it's worse than the aggregator it replaces. Menus rank locally → see [[local-seo]].
• reservations (booking) — Wedge: SevenRooms is upmarket/expensive; give SMBs bookings + waitlist without the price tag. The one thing: it's SMS-first — text-the-waitlist and ready-pings are the product; turn time drives table availability. SMS consent → [[lifecycle-messaging]].
• loyalty (crm) — Wedge: most POS loyalty is points-only; we add offers + win-back. The one thing: lapsed-guest re-engagement (segment by last-visit, send an offer) is where the revenue is — design win-back, not just an earn-points counter. Sends → [[lifecycle-messaging]].
• shift-scheduling (booking) — Wedge: rota + open shifts + swaps cheaper/simpler than the incumbents. The one thing: swaps must enforce coverage rules (min staff per role per time band) — an unconstrained swap that leaves the line uncovered is the failure mode.

6. Compliance (light — defer the heavy lifts)

• Tip pooling / labor law (FLSA) — managers/owners may not share in tip pools; keep tip vs service-charge distinct; honor tip-credit rules. State law varies (e.g. CA). Surface as a constraint; get specifics confirmed.
• Food-allergen disclosure — the big 9 US allergens must be declarable on menu items; some jurisdictions require menu labeling. Model allergen tags on MenuItem.
• SMS consent for waitlist/loyalty — TCPA consent, STOP/HELP, quiet hours apply to every text. Defer the mechanics to [[lifecycle-messaging]].
• Payment — PCI scope, SCA, refunds/chargebacks. Defer billing/payment design to the billing/PCI track; don't hand-roll card handling here.

---

Cross-refs: [[lifecycle-messaging]] (every SMS/email leg — consent + deliver- ability), [[local-seo]] (menus and reservations rank locally; "best tacos near me" is the funnel), [[migration-ready-schema]] (importing an existing menu / guest list from the incumbent POS without losing modifier structure).