MenuGo: Technical & Architectural Documentation

Welcome to the comprehensive technical documentation for MenuGo, a production-ready, multi-tenant, mobile-first QR-code dining and ordering SaaS platform engineered specifically for Myanmar's Food & Beverage (F&B) sector.

📐 1. System Overview & Architecture (Production Complete)

MenuGo is engineered as a high-performance, modular TypeScript monorepo managed via pnpm workspaces. It provides an end-to-end dining platform supporting zero-friction customer mobile ordering, real-time Kitchen Display System (KDS) with sound alerts, waiter table settlement with POS thermal receipts and consolidated bill hubs, business analytics dashboards with interactive visualizations, multi-tenant platform super-administration, and hardened production operations.

                              ┌─────────────────────────────────────────────────┐
                              │            Landing / Mark                               │                   [Port 5172]                   │
                               └────────────────────────┬────────────────────────┘
                                                        │
          ┌─────────────────────────────────────────────┴─────────────────────────────────────────────┐
          ▼                                                                                           ▼
┌─────────────────────────────────┐                                                 ┌─────────────────────────────────┐
│       Customer Mobile Web       │                                                 │         Staff Web (KDS)         │
│  (React 19 + Cart + Bill Hub)   │                                                 │  (React 19 + Recharts + Portals)│
│           [Port 5173]           │                                                 │           [Port 5174]           │
└────────────────┬────────────────┘                                                 └────────────────┬────────────────┘
                 │ Scan QR / REST API                                                                │ JWT / SSE / REST API
                 └──────────────────────────────────────┬────────────────────────────────────────────┘
                                                        │
                                                        ▼
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                   Fastify v4 REST API Service (Node v20 LTS)                                │
│                                                   [Port 3000]                                               │
│                                                                                                             │
│  ┌────────────────────────┐ ┌────────────────────────┐ ┌────────────────────────┐ ┌──────────────────────┐  │
│  │ Public / Customer APIs │ │   Staff Dashboard APIs │ │  Platform Super Admin  │ │ Realtime SSE Streams │  │
│  │ (Session Auth JWT)     │ │   (Staff JWT + RBAC)   │ │  (Super Admin JWT)     │ │ (/orders/stream)     │  │
│  └────────────────────────┘ └────────────────────────┘ └────────────────────────┘ └──────────────────────┘  │
│                                                                                                             │
│  ┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐  │
│  │ Business Services & Domain Engines Layer                                                              │  │
│  │ ├─ OrderService                 ├─ TableSettlementService            ├─ AdminAuditService             │  │
│  │ ├─ OrderLifecycleService        ├─ OperationalMetricsService         ├─ Knayi Zawgyi Converter        │  │
│  │ └─ StorageService               └─ HMAC-SHA256 QR Security Engine    └─ REST Controllers & SSE Stream │  │
│  └───────────────────────────────────────────────────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐  │
│  │ Production Security & Observability Layer                                                             │  │
│  │ ├─ Correlation IDs (x-correlation-id)           ├─ Health & Ready Probes (/healthz, /readyz)          │  │
│  │ ├─ Strict Production Secret Validation          └─ Multi-Tenant Row-Level Security (withTenant tx)    │  │
│  └───────────────────────────────────────────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────┬──────────────────────────────────────────────────────┘
                                                       │ Tenant-isolated Transactions
                                                       ▼
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                     PostgreSQL 16 Database + Drizzle ORM                                    │
│                                                                                                             │
│  ┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐  │
│  │ PostgreSQL Native Row-Level Security (RLS) & Tenant Foreign Keys + Admin Audit Logging                │  │
│  └───────────────────────────────────────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

🛠️ 2. Workspaces & Technology Stack

Monorepo Workspace Structure

.
├── apps/
│   ├── backend/            # Fastify v4 REST API service (Port 3000)
│   │   └── src/
│   │       ├── modules/    # API Route modules (public, staff, admin, events, health, auth)
│   │       ├── services/   # Business services (Order, KDS, Settlement, Analytics, Audit, Storage)
│   │       ├── plugins/    # Error handler & Correlation ID middleware
│   │       └── utils/      # Cryptographic HMAC & Security utilities
│   ├── customer-web/       # Mobile React 19 customer menu client (Port 5173)
│   │   └── src/
│   │       ├── components/ # MenuCards, ModifierModal, CartDrawer, OrderTracker, BillHub
│   │       ├── context/    # CartContext, LanguageContext, CustomerSessionContext
│   │       └── pages/      # MenuPage, OrdersHubPage
│   ├── landing-web/        # Public showcase & Super Admin portal (Port 5172: / and /admin)
│   │   └── src/
│   │       ├── components/ # Hero, FeatureGrid, InteractiveDemo, Pricing, Footer
│   │       └── pages/      # HomePage, PricingPage, SimulatorPage, FaqPage, admin/SuperAdminPage
│   └── staff-web/          # Staff & Kitchen Dashboard client (Port 5174)
│       └── src/
│           ├── components/ # KDSQueue, TableSettlementModal, DailyAnalytics (Recharts), QRModal (Portal)
│           ├── context/    # StaffAuthContext, LanguageContext, SoundAlertContext
│           └── pages/      # OrdersPage, MenuPage, TablesPage, AnalyticsPage, StaffPage, SettingsPage, LoginPage
├── packages/
│   ├── db/                 # PostgreSQL 16 schema (19 tables), Drizzle ORM migrations, seeds, RLS helpers & backup scripts
│   └── shared/             # Monorepo TypeScript interfaces, DTOs, Enums, & Contract schemas
├── docs/                   # Architecture, API, Authentication, and Database specifications
├── PRODUCTION_OPERATIONS.md# Production deployment, backup & operations manual
├── documentation.md        # Full master technical documentation (this file)
└── system usage guide.md   # End-user manual (Customers, Staff, Owners, Super Admins)

Technology Matrix

🔐 3. Security, Multi-Tenancy & Production Hardening

Multi-Tenant Isolation via PostgreSQL Row-Level Security (RLS)

Native PostgreSQL RLS: Every tenant-scoped table enables native RLS (ENABLE ROW LEVEL SECURITY and FORCE ROW LEVEL SECURITY).

Transaction-Scoped Tenant Context (withTenant): All database operations execute inside transaction wrappers injecting the session context:

await withTenant(tenantId, async (tx) => {
  // Queries executed here are strictly constrained by PostgreSQL RLS
  return await tx.select().from(orders).where(...);
});

Cross-Tenant Guard Rails: Pre-handler route guards execute verifyResourceTenantOwnership to reject any cross-tenant tampering attempts with 403 CROSS_TENANT_FORBIDDEN.

HMAC-SHA256 QR Token Cryptographic Architecture

Tamper-Proof Signature: QR codes contain no plain IDs or raw credentials. They carry a cryptographic signature: Signature = HMAC-SHA256(tenantId + ":" + tableId + ":" + tokenVersion + ":" + secretToken, APP_SECRET)
One-Click Instant Revocation: Tenant Admins can regenerate table QR tokens at any time. This atomically increments tokenVersion and generates a new secret, immediately revoking all previously printed physical QR codes.
Timing-Safe Verification: Validation uses crypto.timingSafeEqual to prevent side-channel timing attacks.

Production Hardening & Observability

Strict Environment Validation: In NODE_ENV=production, the server halts immediately if JWT_SECRET or APP_SECRET use default dev keys or are shorter than 32 characters.
Diagnostic Correlation IDs: Every inbound request receives a unique x-correlation-id header attached to both success and error responses for distributed tracing.
Health & Readiness Endpoints:
- GET /healthz: Liveness probe verifying process uptime and memory health.
- GET /readyz: Readiness probe testing active PostgreSQL database connectivity (SELECT 1).
Comprehensive Rate Limiting: Built-in IP rate limiting protects verification endpoints (max 20 req/min) and order placement endpoints (max 15 req/min per session).

🧩 4. Business Services & Domain Engines

MenuGo decouples core domain logic into robust business services in apps/backend/src/services/:

1. `OrderService` (`order.service.ts`)

Idempotency Safeguard: Accepts X-Idempotency-Key headers to eliminate duplicate charges on flaky cellular mobile connections.
Financial Calculation Engine: Computes exact item subtotals, modifier prices (+MMK), tax amounts, discounts, and net totals.
Stock Availability Verification: Revalidates stock availability (is_available = true) and active category status in real time before accepting orders.

2. `OrderLifecycleService` (`order-lifecycle.service.ts`)

KDS State Machine: Governs strict state transitions: PENDING → ACCEPTED → PREPARING → READY → DELIVERED → CLOSED / CANCELLED
Immutable Audit History: Writes every fulfillment and payment status change to order_status_history with the changing user ID and timestamp.
Automatic Session Invalidation: Inactivates table_sessions when all active orders for a table reach CLOSED or CANCELLED.

3. `TableSettlementService` (`table-settlement.service.ts`)

Consolidated Bill Hub: Aggregates all open, unclosed orders for a table into a unified bill statement.
Multi-Method Payment Settlement: Supports recording of CASH, KBZ_PAY, WAVE_PAY, and OTHER, transitioning payment status from UNPAID to PAID.
Offline Payment Record-Keeping (Important): MenuGo does not integrate payment gateways. KBZ_PAY / WAVE_PAY / OTHER are record-keeping labels only — the customer pays the waiter directly (cash transfer or in-app wallet transfer), and staff record which channel was used on the settlement receipt. No funds flow through MenuGo.
Change Calculation & Thermal Printing: Computes cash change and generates formatted ESC/POS-compatible thermal receipt payloads for 80mm/58mm POS receipt printers.

4. `OperationalMetricsService` (`operational-metrics.service.ts`)

Analytics & Reporting: Aggregates daily net revenue (MMK), total order volume, average fulfillment duration, hourly sales distributions, and top-selling menu items.

5. `AdminAuditService` (`admin-audit.service.ts`)

Security Audit Logging: Captures all platform administrative operations (tenant creation, user suspension, role changes) into admin_audit_logs.

6. `StorageService` (`storage.service.ts`)

Isolated Asset Management: Handles tenant-isolated image uploads (/uploads/:tenantId/) with strict MIME type and file size validation (max 5 MB).

🗄️ 5. Database Schema & Data Models

Entity Relationship Matrix (PostgreSQL 16 — 19 Production Tables)

📡 6. Complete API Specifications

Public / Customer Endpoints (`/api/v1/pub/...`)

Staff & Operations Endpoints (`/api/v1/staff/...`)

Platform Super Admin Endpoints (`/api/v1/admin/...`)

🧪 7. Automated Testing & Verification Suite

MenuGo maintains automated test suites covering tenant isolation, dual-session authentication, QR security, menu stock toggling, KDS state machines, settlement calculations, platform admin operations, SSE streaming, and pilot E2E dining workflows. All tests feature automatic database artifact cleanup in afterAll hooks to prevent database pollution.

# Run full automated test suite across monorepo
pnpm test

# Run individual targeted test suites
pnpm test:auth        # Dual-session JWT & RBAC permission tests
pnpm test:qr          # Cryptographic HMAC QR signature & revocation tests
pnpm test:menu        # Menu CRUD, modifier options, & 86 stock toggle tests
pnpm test:order       # Order submission, idempotency, & financial calculation tests
pnpm test:kds         # Kitchen Display System queue & state machine tests
pnpm test:settlement  # Multi-order table bill aggregation & payment settlement tests
pnpm test:staff       # Staff management & access control tests
pnpm test:admin       # Platform Super Admin & audit logging tests
pnpm test:sse         # Realtime SSE event streaming tests
pnpm test:e2e         # End-to-end dining pilot simulation test

⚡ 8. Monorepo Quality & Verification Commands

# Verify TypeScript strict type-checking across all 5 apps and 2 packages
pnpm typecheck

# Check code linting and style rules
pnpm lint

# Check code formatting compliance (Prettier)
pnpm format:check

# Build all production bundles
pnpm build

MenuGo