Documentation
Documentation
Everything you need to run Zest.
Getting Started
Prerequisites
- Node.js 20+ (LTS recommended)
- pnpm 9+
- macOS for BLE thermal printer support
- Xcode CLI tools (for native builds)
Installation
Terminal
git clone https://github.com/ec812/zestcd zestpnpm installpnpm devThe dev server starts on http://localhost:3898
Available Scripts
| Command | Description |
|---|---|
| pnpm dev | Start dev server (port 3898) |
| pnpm build | Production build |
| pnpm start | Start production server |
| pnpm lint | Run ESLint |
| pnpm test | Run unit tests |
Features
Customer-Facing
| Feature | Route | Description |
|---|---|---|
| Public Menu | / | Trilingual dish menu (Japanese, English, Chinese) grouped by category |
| Table Ordering | /order/[qr_code] | Scan a table QR code to browse the menu, add rounds, view the bill |
| Bill View | /bill/[qr_code] | Read-only bill for an open table order |
| Reservations | /book | Public booking form (name, party size, date/time, contact) |
| Customer CLI | zest | Agent-friendly CLI for menu browsing, ordering, and status checks |
Staff Admin
| Feature | Route | Description |
|---|---|---|
| Dashboard | /admin | Stats, active orders, today's bookings, top-selling dishes |
| Dishes | /admin/dishes | CRUD for menu items, image upload, AI-assisted trilingual fill |
| Tables | /admin/tables | Manage tables, QR codes, capacity, sections |
| Orders | /admin/orders | Kanban order board with real-time SSE updates |
| Bookings | /admin/bookings | Calendar and list views for reservations |
| Variants | /admin/variants | Variant groups and options (e.g. size, temperature) |
| Time Slots | /admin/time-slots | Breakfast / lunch / dinner windows with per-dish pricing |
| Settings | /admin/settings | Theme, service charge, basic fee, address, printer names |
Backend Capabilities
- Trilingual data model — every dish, time slot, and description carries *_ja, *_en, and *_zh fields
- Role-based API auth — super_admin, admin, and staff with scoped permissions
- Round-based ordering, per-item kitchen status, service charge, basic fee, payment tracking
- Dine-in and takeaway — table QR orders and takeaway with pickup codes
- Real-time updates — Server-Sent Events (/api/orders/stream) for live order board
- Thermal printing — ESC/POS kitchen tickets and receipts via BLE
- Rate limiting — sliding-window limits on public order endpoints
Customer CLI
The zest CLI lets customers and AI agents browse the menu, place orders, and check status — all from the terminal.
Installation
Terminal
npm install -g zest-cli# or run without installing:npx zest-cli <command>Commands
| Command | Description |
|---|---|
| zest menu | List all available dishes |
| zest menu --category sashimi --pretty | Filter by category with human-readable output |
| zest dish <id> | Show details for a single dish |
| zest order --mode dine-in --table T01 --items '[...]' | Place a dine-in order |
| zest order --mode takeaway --name John --phone 5555 --items '[...]' | Place a takeaway order |
| zest status <order_id> | Check order status and items |
| zest info | Show restaurant settings |
| zest configure | Create config with API URL and customer token |
Output Formats
- Default output is compact JSON (agent-friendly)
- --pretty enables human-readable terminal output with formatted prices
Configuration
The CLI stores settings in ~/.zest/config.json. Run zest configure to create this file automatically.
API URL precedence
- 1. ZEST_API_URL environment variable
- 2. apiUrl in ~/.zest/config.json
- 3. Default: http://localhost:3898
Tech Stack
| Layer | Technology |
|---|---|
| Framework | Next.js 16 (App Router) + React 19 |
| Language | TypeScript 5 |
| Database | SQLite via better-sqlite3 (WAL mode) |
| Styling | Tailwind CSS v4 + shadcn/ui |
| Auth | bcrypt + SHA-256 API keys (sk- prefix) |
| Printing | ESC/POS, @abandonware/noble (BLE) |
| AI | DeepSeek API (optional) |
| CLI | Commander.js + Axios |
| Package Manager | pnpm (monorepo) |
Configuration
Restaurant Settings
Configure your restaurant via the /admin/settings page. All settings are stored in SQLite and accessible via the REST API.
- Theme — 4 built-in color themes (Sage Green, Ocean Blue, Crimson Red, Lavender Purple)
- Dark mode — toggle between light and dark appearance
- Service charge — enable/disable, set percentage (applied to orders)
- Basic fee — per-person cover charge
- Restaurant address and phone number
- Printer names — configure kitchen and bar printer targets
Themes
Sage Green
Warm, earthy green — the original Zest palette
Ocean Blue
Cool, deep blue inspired by the sea
Crimson Red
Bold, rich crimson with depth
Lavender Purple
Soft, elegant purple tones
Thermal Printing
Zest supports BLE thermal printers for kitchen tickets and receipts. On macOS, printers must NOT be paired in System Settings — GATT access is required.
- Kitchen tickets — food items go to kitchen printer, drinks to bar printer
- Receipts — formatted bill with itemized charges, service fee, and total
- QR code printing — print table QR codes directly to thermal printer