Group Ordering App

A production-ready Next.js 15 + TypeScript application for restaurant group ordering. Staff can import menus, configure ordering events, collect customer orders, and monitor the kitchen dashboard with Supabase Realtime updates.

Prerequisites

• Node.js 18+
• npm (or pnpm/yarn)
• Supabase project (Postgres + Realtime enabled)
• Optional: Resend account for transactional email

Local Setup

1. Install dependencies:

   npm install

2. Copy environment variables:

   cp .env.local.example .env.local

3. Populate .env.local:

   NEXT_PUBLIC_SUPABASE_URL=
   NEXT_PUBLIC_SUPABASE_ANON_KEY=
   SUPABASE_SERVICE_ROLE_KEY=
   ADMIN_PASSCODE=change-me
   RESEND_API_KEY=
   EMAIL_FROM=orders@example.com
   RESTAURANT_NOTIFICATION_EMAIL=team@example.com
   RESTAURANT_NAME="Example Kitchen"
   RESTAURANT_TZ="America/Chicago"
   

   RESEND_API_KEY, EMAIL_FROM, and RESTAURANT_NOTIFICATION_EMAIL are optional; the app logs stubbed emails when they are not supplied.
4. Create the database schema in Supabase:

   psql "$SUPABASE_CONNECTION_STRING" -f supabase/migrations/0001_initial.sql

   or paste the migration into the Supabase SQL editor.
5. Seed the sample menu (optional but useful for local testing):

   npm run seed

6. Start the dev server:

   npm run dev

   Visit http://localhost:3000 for the customer flow, /admin/login for staff, and /kitchen after authenticating.

Menu Imports

Sample data lives in /data/menu.yaml and /data/menu.csv. Upload either file from /admin/menu-import to load categories, items, options, and option values. Imports compute a diff (created / updated / removed) and upsert records so incremental edits are safe. Re-run imports any time you tweak prices or modifiers.

CSV headers expected by the importer:

category,category_sort,item_id,item_name,item_desc,price,sku,item_sort,opt_group,opt_type,opt_required,opt_label,opt_price_delta

Key Workflows

• /events: Public calendar showing OPEN and UPCOMING events.
• /menu: Customer menu with modifier dialogs, cart drawer, and checkout redirect when an event is open.
• /checkout: Validates customer details and places the order via Supabase service role pricing.
• /success: Lightweight confirmation page with pickup code.
• /admin + /admin/events + /admin/menu: Staff tools for events and item visibility.
• /admin/menu-import: YAML/CSV importer with diff summary.
• /kitchen: Tablet-friendly dashboard with realtime updates and aggregate counts.

Mobile UX Patterns Used

• Safe-area aware bottom bars for the menu cart and checkout submission flows.
• Responsive customer pages (mx-auto max-w-screen-sm px-4) with single-column layouts that scale gracefully.
• Bottom sheet + desktop modal pairing for menu customization, plus collapsible mobile cart drawer.
• Sticky segmented control on the kitchen dashboard (Pending → Preparing → Ready → Picked up) with realtime highlights and audible chimes for new orders.
• Inline Sonner toasts for add-to-cart, status changes, and checkout success/failure feedback.
• Skeleton loading.tsx files for events, menu, and kitchen to eliminate perceived loading jank.

Extending the Design System

• Global design tokens live in src/app/globals.css (--bg, --card, --primary, --ring, --radius, --shadow-*). Tweak these variables to restyle the app without editing components.
• Utility classes (.btn*, .input, .card, .safe-top, .safe-bottom, etc.) are also defined in globals.css under @layer utilities for reuse across pages.
• UI primitives (Button, Card, Input, Dialog) live in src/components/ui/—extend these components to add new variants or sizes instead of sprinkling bespoke Tailwind classes.
• Customer flows should stay within mx-auto max-w-screen-sm px-4 containers; staff/kitchen views use mx-auto max-w-screen-lg px-4.
• The responsive Dialog component supports variant="center" (modal), variant="bottom" (sheet), and variant="sidebar" (drawer) for consistent overlay behavior.

Testing

• Lint: npm run lint
• Type check + build: npm run build
• Playwright end-to-end smoke tests: npm run test:e2e
  • Requires the dev server running (npm run dev), seeded data, and PLAYWRIGHT_E2E=true in the environment to opt-in.
  • Tests live in tests/playwright; manual acceptance steps are documented in tests/ACCEPTANCE.md.

Emails

Order confirmations are sent to the customer and mirrored to RESTAURANT_NOTIFICATION_EMAIL when Resend credentials are available. Without credentials the app logs stub messages to the server console.

Deployment

1. Push to GitHub and connect the repository to Vercel.
2. Set the following environment variables in Vercel (all “Production” and “Preview” scopes):
   • NEXT_PUBLIC_SUPABASE_URL
   • NEXT_PUBLIC_SUPABASE_ANON_KEY
   • SUPABASE_SERVICE_ROLE_KEY
   • ADMIN_PASSCODE
   • RESEND_API_KEY (optional)
   • EMAIL_FROM (optional)
   • RESTAURANT_NOTIFICATION_EMAIL (optional)
   • RESTAURANT_NAME
   • RESTAURANT_TZ
3. Run npm run build during the Vercel build step.
4. In Supabase, enable Realtime for orders and order_items (already in the migration).
5. After deploying, run the menu seed once (via npm run seed locally or the admin importer) to populate baseline data.

Repository Highlights

• src/lib/menu-import.ts – CSV/YAML parsing, diffing, and Supabase upserts.
• src/lib/orders-service.ts – Server-side pricing, order creation, summary utilities, and realtime broadcasting.
• src/components/menu/menu-client.tsx – Customer menu composer and cart drawer.
• src/app/(staff)/kitchen – Realtime kitchen dashboard with status controls and aggregates.
• scripts/seed-menu.ts – Optional CLI seed that imports data/menu.yaml.

Acceptance Checklist

Manual smoke testing steps are captured in tests/ACCEPTANCE.md and cover menu imports, event creation, customer orders, kitchen updates, item visibility toggles, and menu refreshes.