Skip to content

Latest commit

 

History

275 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

CulinaryOS

The unified restaurant technology operating system. Humans on POS/KDS, edge nodes on Raspberry Pi, agents on MCP, sovereign Postgres. MIT licensed.

Tests: Passing Typecheck: Passing UI: OKLCH + 6--State License: MIT TypeScript Version


🍽️ Target Product Family

CulinaryOS is the single primary restaurant technology monorepo, consolidating the full spectrum of food-service operations into a coherent, modular platform:

CulinaryOS
├── Core           — Multi-tenant auth, session tokens, PostgreSQL RLS, offline event bus
├── POS            — Front-of-House terminal (offline-first, table mapping, split checks)
├── KDS            — Kitchen Display System (station routing, cook times, course pacing)
├── Admin          — Back-office workstation (manager PIN gate, HACCP operations HUD)
├── Ordering       — Omnichannel dining room, tableside QR, and online guest checkout
├── Inventory      — Stock tracking, auto-depletion, vendor SKUs, and purchase orders
├── Prep           — Batch prep planning & recipe vault (absorbs KitchenKit + RecipeOS)
├── Ops            — Prime cost, actual vs. theoretical food cost, FLSA labor, waste (absorbs CulinaryOps)
├── Marketing      — Autonomous campaigns, brand guardrails, review replies (absorbs Post-Pilot)
├── Web            — Public restaurant experience & 8 Astro themes (absorbs Plated)
├── Intelligence   — Vendor-neutral AI skills, 6 role agents, anomaly detection (absorbs RestRevive)
├── Integrations   — Stripe Terminal/Connect, Star/Epson ESC/POS, Mercury, partner APIs
├── Edge           — Raspberry Pi 5 / CM5 local appliance with Rust high-reliability services
├── SDK            — Unified `@culinaryos/sdk` service boundary for first & third parties
└── MCP            — Restaurant-specific Model Context Protocol tools for AI pairing

Ecosystem Boundaries:

  • ShorelineOps: Remains an independent specialized healthcare vertical; integrates via APIs, SDK, events, and MCP tools. Never coupled to internal database schemas.
  • MuseLab: Experimental incubation environment for Meta Muse / XR prototypes; zero production dependencies in CulinaryOS.
  • ForgeSatchel & JOSH: Decoupled developer framework and System 1 router; integrated via clean adapters.

🧭 Current Architecture & Standards

  1. Local-First & Offline Resilient: Internet outages must never halt restaurant service. POS order entry, KDS ticket routing, local ESC/POS printing, and offline card intent queues run on local edge hardware and reconcile idempotently.
  2. Industrial UI/UX Ergonomics: 48px physical touch target minimums, 6-state button engine (Idle, Hover, Focus-Visible, Active scale physics, Loading fixed bounds, Disabled), and OKLCH color space with WCAG AA high-glare kitchen contrast.
  3. Security & Money Integrity: Every tenant-scoped table enforces PostgreSQL RLS. All payments calculated in integer cents. Cardholder data never touches application servers (Stripe Terminal SAQ-A outsourcing).
  4. Vendor-Neutral AI: Business logic is never coupled to Anthropic, Google, or OpenAI. Swappable via ProviderAdapter. AI is strictly additive, behind feature flags, and requires human-in-the-loop approvals for sensitive operations.

What is CulinaryOS?

CulinaryOS covers every surface of modern hospitality:

  • Desktop Workstation (:5180) — Unified restaurant workstation with F1–F7 hotkeys, PIN manager, and full-screen Kiosk mode.
  • POS Terminal (:5172) — PIN-authenticated, offline-first, multi-tender (card, tap, QR, cash, comp) with ESC/POS hardware thermal printing.
  • Kitchen Display System (:5173) — Real-time ticket aging, station routing, multi-course hold/fire with high-contrast OLED mode, and sub-second course pacing.
  • Admin Back-Office (:5174) — Manager PIN gated, dual-column HACCP operations hub, menu builder, staff PINs, and operations HUD.
  • CulinaryOS Prep (:5177) — Recipe formulas, ratio blueprints, batch sizing, FIFO QR labels, and shift prep lists.
  • Online Storefront & Web (:5176) — Guest ordering with FDA Top 9 dietary filtering, allergen matrices, tableside QR pay, and Plated theme generator.
  • CulinaryOS Ops (:5178) — Actual vs theoretical food cost variance, kitchen scrap logging, FLSA tip pools, and labor % tracking.
  • Marketing Studio (:5179) — AI brand guardrails, 3-stage event campaign generator, and review response automation.
  • Unified Hono API (:3000) — Single source of truth for orders, inventory, ops, payments, and settings.
  • MCP Server (mcp/) — Specialized Model Context Protocol servers exposing restaurant operations to AI agents.

All surfaces share a single Supabase PostgreSQL backend with Row Level Security (RLS) enforcing strict multi-tenant isolation. The AI layer is strictly additive and off by default — every core operation works identically without external AI APIs.


🛠️ Universal CLI Tool (culinary)

CulinaryOS includes a full-featured CLI offering 100% parity across all 18 operational subsystems:

# Build the CLI tool
pnpm --filter culinary-cli build

# Front-of-House POS Operations
culinary pos list                              # View active dining room orders
culinary pos seat 4 --covers 4                 # Seat guests at Table 4
culinary pos fire 4 "Burger" "Pizza"           # Ring up & fire items to kitchen
culinary pos merge 5 4 6                       # Merge tables 4 & 6 into Table 5
culinary pos void ord-1 item-2 "Overcooked" 5678 # Void post-send item with Manager PIN
culinary pos pay ord-1 --method card           # Settle bill with card / tap

# Back-of-House Kitchen Display & Pacing
culinary kds list                              # View live kitchen tickets & aging
culinary kds bump tkt-101 --station expo       # Bump completed ticket
culinary kds fire-course ord-1 2               # Fire Course 2 (Entrees)
culinary kds 86 "Ribeye" 4                     # Set 86 countdown: 4 remaining
culinary kds pacing                            # Monitor course pacing, C2 hold times & alerts

# Food Cost, Labor & Operations Coaching
culinary ops waste item-3 5.0 "Burnt"          # Log kitchen scrap & auto-calculate loss
culinary ops food-cost                         # Actual vs theoretical food cost variance
culinary ops labor                             # Shift labor hours & labor % report
culinary ops coach                             # Run operations coaching & bottleneck audit

# Reservations, Talent, Billing & Pantry Parity
culinary reservations list                     # View dining room table reservations
culinary talent staff                          # View staff roster, roles & active clock-ins
culinary billing status                        # Inspect Stripe Connect & subscription status
culinary pantry stock                          # Real-time pantry stock grams & par levels
culinary tabs list                             # View active bar and dining tabs

# Multi-Unit Commissary, AI Kitchen Autopilot & Dynamic Dayparts
culinary commissary transfers                  # View incoming/outgoing stock transfers
culinary commissary request "Patties" 100      # Place central replenishment order
culinary commissary royalty                    # Brand-wide franchise royalty ledger
culinary autopilot status                      # Verify Rule 6 AI feature flag state
culinary autopilot forecast --daypart dinner   # Predictive rush covers & revenue forecast
culinary autopilot tokens                      # Inspect ai_prompt_log token burn & cost
culinary dayparts list                         # View scheduled daypart & happy hour rules
culinary dayparts active                       # View currently effective pricing window

# System Diagnostics, Security & Hardware Certification
culinary system doctor                         # Port scan & health diagnostic
culinary system doctor security                # Audit RLS, webhook signatures & manager gates
culinary system hardware --action kick-drawer  # Test 24V RJ12 cash drawer kick
culinary system hardware --action test-page    # Print ESC/POS printer alignment diagnostic
culinary system heal                           # Auto-kill zombie conflicting processes
culinary system tray                           # Launch Windows skillet tray daemon
culinary system discover                       # Broadcast mDNS (culinaryos.local) & QR

Architecture

graph TB
    subgraph Clients
        DSK["Desktop Workstation :5180\nReact + Vite + Dual Pane Split"]
        POS["POS Terminal :5172\nReact + Vite + Three.js"]
        KDS["KDS Display :5173\nReact + Vite + KitchenKit"]
        ADM["Admin Portal :5174\nReact + Vite"]
        WEB["Online Storefront :5176\nReact + Vite"]
        KIT["KitchenKit :5175\nReact + Vite"]
        OPS["CulinaryOps :5177\nReact + Vite"]
        REC["RecipeOS :5178\nNext.js App Router"]
        MOB["Mobile Companion\nReact Native + Expo (Android/iOS)"]
    end

    subgraph API["apps/server :3000 — Hono on Node.js 20"]
        AUTH["/v1/auth"]
        ORD["/v1/orders"]
        KDS_API["/v1/kds"]
        PAN["/v1/pantry"]
        OPS_API["/v1/ops"]
        MKT["/v1/marketplace"]
    end

    subgraph Packages
        EB["@culinaryos/event-bus\npos:order:created\nkds:ticket:bumped"]
        RE["@culinaryos/ratio-engine\nRecipe scaling & costing"]
        SH["@culinaryos/shared\nDietary engine, offline-sync"]
        UI["@culinaryos/ui\nshadcn/ui + Three.js + Theme Engine"]
        DB["@culinaryos/db\nSupabase types V1–V14"]
    end

    subgraph Data["Data Layer"]
        SB[("Supabase\nPostgreSQL + RLS\nRealtime")]
    end

    subgraph MCP["MCP Agent Layer (mcp/)"]
        MCP1["culinaryops-server"]
        MCP2["recipe-server"]
        MCP3["kds-server"]
        MCP4["pos-server"]
        MCP5["inventory-server"]
        MCP6["prep-server"]
        MCP7["post-pilot-server"]
    end

    DSK --> POS
    DSK --> KDS
    DSK --> ADM
    POS --> API
    KDS --> API
    ADM --> API
    WEB --> API
    KIT --> API
    OPS --> API
    REC --> API
    MOB --> API

    API --> Packages
    API --> Data
    Packages --> Data

    MCP --> API
Loading

🎨 shadcn/ui Design System & Universal Theme Engine

CulinaryOS includes a centralized design system in @culinaryos/ui built on Radix UI, Tailwind CSS, and Three.js, with a live Theme Customizer:

Theme Presets

  • Classic Bistro (Light): Clean warm linen, balanced typography, elegant fine dining.
  • Midnight Slate (Dark): Deep navy slate (#090d16), cyan accents, low-light evening bar feel.
  • Kitchen OLED (Pure Black #000000): Zero eye strain high-heat high-contrast mode for busy commercial kitchen lines.
  • Cyberpunk Neon: Electric cyan (#06b6d4), magenta accents, modern lounge style.
  • Botanical Garden (Emerald): Forest green (#047857), sage, warm cream farm-to-table aesthetic.
  • Bordeaux & Wine: Intimate steakhouse, ruby crimson (#e11d48), rich deep tones.

Micro-Interaction Animations

  • .animate-ticket-arrive: Spring bounce animation (cubic-bezier(0.34, 1.56, 0.64, 1)) on order fire.
  • .animate-ticket-bump: Smooth exit slide & scale fade on KDS ticket completion.
  • .animate-scale-spring: Elastic button pop and table focus feedback.

See docs/UI_THEME_CUSTOMIZER.md for direct CSS token export and React usage.


Surfaces & Applications

Package Port / Target Role
apps/desktop :5180 Desktop Workstation Hub — Unified split-screen manager, F1–F6 hotkeys, theme switcher, kiosk mode
apps/marketing :5179 CulinaryOS.io SaaS Portal — Next.js 14 marketing, pricing matrix, trial signup, blog, and RecipeOS showcase
apps/server :3000 Unified Hono API — authentication, orders, KDS, reservations, pantry, payments, billing, ops, marketplace
apps/pos :5172 POS terminal (PIN login, 2D/3D floor map, ESC/POS hardware printer hub, live text scaling, PWA offline)
apps/kds :5173 Kitchen Display System (real-time tickets, station filters, course hold/fire, TV 140% mode, PWA offline)
apps/admin :5174 Admin portal — menu editor, staff PINs, custom role builder, pantry par levels, system settings, themes
apps/kitchenkit :5175 KitchenKit — Recipe catalog, station prep planner, par levels, vendor management, shelf life
apps/web :5176 Online ordering storefront (FDA Top 9 dietary filtering, cart customization, instant checkout)
apps/ops :5177 CulinaryOps — Real-time food cost analytics, waste logging, labor %, and vendor performance
apps/recipeos :5178 RecipeOS — Next.js recipe vault, ratio scaling engine, unit conversions, and shopping list
mobile/ Android/iOS React Native + Expo Mobile POS with offline SQLite cache
packages/sdk Shared @culinaryos/sdk — Official TypeScript Client SDK for orders, KDS, reservations, billing, reports
packages/commissary-engine Shared Multi-unit stock replenishment, central production batching, and franchise royalty ledgers
packages/forecast-engine Shared Predictive kitchen demand smoothing, bottleneck advisories, and adaptive safety-stock par levels
packages/loyalty-engine Shared Customer points, digital punch cards, gift card redemption, and dual-sided referral credits
packages/accounting-engine Shared Double-entry General Ledger reconciliation, QuickBooks Online IIF, Xero CSV, and P&L metrics
packages/ui Shared Centralized shadcn/ui design system, Three.js 3D canvas, and Universal Theme Engine
packages/shared Shared Unified settings engine, dietary filter engine, printer driver, offline-sync delta engine
packages/ratio-engine Shared Baker's percentage calculations, yield formulas, and batch scaling
packages/prep-engine Shared Recipe prep task management and batch requirement calculations
packages/food-cost-engine Shared Pure functions for actual vs theoretical food cost variance calculations
packages/waste-engine Shared Kitchen waste summarization and top cost-leakage analysis
packages/labor-engine Shared Shift labor hours, role-weighted tip pooling, and labor cost percentage calculations
packages/pdf-tools Shared Print-ready PDF menu export, Z-Report financial closeout PDF, and QR code generators
packages/template-engine Shared Multi-concept restaurant website and menu template token engine
packages/seo-tools Shared Schema.org JSON-LD structured data generators for restaurant menus and locations
packages/asset-tools Shared OpenGraph banner generator (satori), favicons, and palette extractors
mcp/ Extension 9 Model Context Protocol servers + Python Post-Pilot loyalty agent

Quick Start (Local Demo Mode)

Run the entire system locally in under 30 seconds with zero database setup and zero external API keys:

Prerequisites

Boot

# 1. Clone repository and install dependencies
git clone https://github.com/ShadowWalkerNC/CulinaryOS.git
cd CulinaryOS
pnpm install

# 2. One-command turnkey boot (launches Desktop Hub, POS, KDS, Admin, Web, and API)
pnpm quickstart

(On Windows you can also run .\scripts\install.ps1, or ./scripts/install.sh on macOS/Linux).

Interactive walkthrough: See QUICKSTART.md.

Demo Credentials

Surface URL Credential
Desktop Workstation localhost:5180 F1–F6 quick switch · Kiosk mode · Split view
POS Terminal localhost:5172 Demo mode PINs: 1234 (server) · 5678 (manager) — demo PINs are rejected on live/production paths
Kitchen Display (KDS) localhost:5173 No login required
Admin Portal localhost:5174 No login required
Online Storefront localhost:5176 No login required
KitchenKit localhost:5175 No login required
CulinaryOps localhost:5177 No login required
RecipeOS localhost:5178 No login required
Unified Hono API localhost:3000 X-Tenant-Id: 00000000-0000-0000-0000-000000000001

In offline/demo mode, POS serves a sample menu, buffers transactions to localStorage, and communicates with the in-memory mock kitchen store on the API. POS and KDS do not share live state in demo mode — use a live Supabase backend for cross-app POS→KDS order flow.


Operations Consultant & Daily Audits

CulinaryOS includes an autonomous Restaurant Operations Manager & Consultant framework for continuous review of hospitality workflows:

# Run daily operations audit & generate report
pnpm ops:audit

# View the latest operational critique
cat docs/DAILY_OPERATIONS_REPORT.md

The audit evaluates speed-of-service, touchscreen ergonomics, KDS course hold/fire timers, FDA Top 9 allergen classifications, and shared fryer cross-contact risks, and generates targeted daily operational questions for engineering refinement.


Connecting to Live Supabase Backend

To enable multi-device sync, PostgreSQL Row Level Security (RLS), and live Supabase Realtime:

  1. Provide valid keys in .env:
    SUPABASE_URL=https://your-project.supabase.co
    SUPABASE_ANON_KEY=eyJ...
    SUPABASE_SERVICE_ROLE_KEY=eyJ...
    AUTH_RELAXED=false
  2. Apply database migrations:
    npx supabase db reset
  3. Seed multi-organization, multi-venue demo data:
    pnpm seed
    # Applies: base_tenant.sql → menu.sql → demo.sql → multi_venue_orgs.sql
    # Seeds >= 2 Organizations, >= 3 Venues (Bistro, Commissary, Food Truck), recipes, and PO cycle
  4. Start the stack — POS, KDS, Admin, and MCP agents will now operate on your live database with strict tenant isolation.

See docs/DEPLOYMENT.md and docs/architecture.md for multi-venue architecture and Docker options.


Security Posture

Security and money-accuracy outrank shipping speed. Current enforcement:

  • Fail-closed authentication — auth denies by default; relaxed/demo modes require explicit opt-in, never the default.
  • Demo PINs are demo-only — 1234 / 5678 are rejected on live/production paths, and PIN entry is throttled against brute force.
  • Server-authoritative money — menu prices are enforced server-side; clients can never set their own prices. Financial math uses integer cents, never floats.
  • No card data, ever — no PAN storage, no CVV, card data never in logs. Card-present flows go through Stripe Terminal only.
  • Manager gates on sensitive actions — comp tenders require a manager PIN; refunds and voids are permission-checked.
  • No bundled secrets — service-role keys never ship in client bundles; credentials live in server env only.

See docs/security.md and AGENTS.md for the full ruleset.

Quality & Testing Gate

CulinaryOS enforces strict quality gates across the monorepo:

# Run complete test suite (121 test suites across all packages and surfaces — 100% green)
node ./scripts/run-all-tests.cjs

# Run workspace-wide typecheck (18 tasks across all packages — 0 errors)
pnpm run typecheck

# Build all packages and applications
pnpm run build

# Run production readiness preflight doctor
pnpm doctor

Note on lint: pnpm run lint is currently non-functional (eslint configs pending). Use pnpm typecheck as the static analysis gate.

Note on pnpm test: The Turborepo root #test task has a known recursive-invocation issue. Use node ./scripts/run-all-tests.cjs or bun test tests/server/ directly.


Repository Structure

CulinaryOS/
├── apps/
│   ├── server/          ← Unified Hono API (orders, KDS, pantry, ops, payments)
│   ├── pos/             ← POS terminal (React / Vite / shadcn / Three.js)
│   ├── kds/             ← Kitchen Display client (React / Vite)
│   ├── admin/           ← Admin / pantry portal (React / Vite)
│   └── web/             ← Online ordering storefront (React / Vite)
├── packages/            ← shared, event-bus, auth, db, ui, config, ratio-engine
├── mcp/                 ← 9 MCP servers — AI agent tool layer
├── extensions/          ← First-party extension manifests
├── extension_template/  ← Public contract for third-party extensions
├── mobile/              ← React Native + Expo companion (stub)
├── supabase/            ← Migrations + seeds (V1–V14)
├── cli/                 ← Operator CLI tool
├── tests/               ← Integration + e2e tests
├── docs/                ← Technical documentation
├── scripts/             ← quickstart, seed, doctor, simulate, ops-audit
├── docker-compose.yml   ← Production container build
├── pnpm-workspace.yaml  ← Monorepo workspace config
├── turbo.json           ← Turborepo pipeline config
└── .env.example         ← All required env vars

Screenshots

All screenshots captured live from the running application.

3D Spatial Floor Plan & Table Management

3D Floor Plan with table status rings

Kitchen Display System (KitchenKit — Station Routing)

KDS with station tabs and aging timers

POS Terminal — Multi-Seat Ticket Menu

POS multi-seat ticket ordering

Online Customer Storefront

Online ordering with allergen filtering

Additional Screens

POS Hardware & Thermal Printer Hub POS Checkout & Receipt Tape POS Recall & Audit Screen

Admin Pantry & Auto-PO Admin Menu & 86 Editor Admin Operations Ledger


Contributing

We welcome contributions! Please read CONTRIBUTING.md before opening a PR.

  • Branch naming: feature/[module]-[description] · fix/[module]-[issue] · docs/[scope]
  • Commit format: Conventional Commits — feat(pos): ..., fix(kds): ..., docs(readme): ...
  • Non-negotiable: every database query must be scoped by tenant_id / RLS. Unscoped queries are rejected.

Community & Support


License

MIT — Own your stack. Built with TypeScript, React, Vite, Three.js, Radix UI, Hono, Supabase, Turborepo, and Model Context Protocol (MCP).

Releases

Packages

Contributors

Languages