PeyePeye PEYEPEYE
PeyePeye

PeyePeye — Core Platform MVP Scope

Shared Infrastructure & Backend Services

The backend and shared services powering both the Diner App and Restaurant App. This document covers authentication, payments, data architecture, real-time services, AI processing, compliance, APIs, and infrastructure.

Table of Contents

  1. Authentication & Identity
  2. Payment Processing
  3. Data Layer — MongoDB + Zod
  4. Real-Time Services
  5. AI Processing Layer
  6. SOC 2 Compliance Features
  7. API & Documentation
  8. POS Integration Layer (Post-MVP)
  9. Infrastructure & Deployment
  10. MVP Scope Boundaries

1. Authentication & Identity

Component Description MVP Implementation
Phone verification SMS-based verification Twilio Verify API
Carrier identity check Prove / Payfone API POST-MVP — use simple phone/SMS for MVP
Session management JWT tokens, refresh tokens, device management jsonwebtoken + refresh rotation

Authentication Flow

Phone Entry SMS Code Verify Create Session (JWT) PeyePeye Verified
Technical Note: JWTs use RS256 signing with 15-minute access token expiry and 7-day refresh token rotation. Refresh tokens are stored in an HTTP-only secure cookie and invalidated on logout or suspicious activity.

2. Payment Processing

Stripe vs. Finix Comparison

Component Description Stripe Finix
Card tokenization Securely store card data Stripe.js Elements Finix.js tokenization
Pre-authorization Temporary holds when diner links to table PaymentIntents with capture_method=manual Authorizations API
Charges Final charge at tab close Capture PaymentIntent Create Transfer from Authorization
Refunds Process refunds Refund API Refund API
Connect payouts Route funds to restaurants Stripe Connect (Standard or Express) Merchant onboarding + payouts
Processing fees Per-transaction cost 2.9% + $0.30 Custom (typically 2.7–2.9% + $0.25–0.30)

Payment Lifecycle Flow

Diner Links to Table Pre-Auth Hold ($150) Orders During Meal Tab Accumulates Diner Pays (or Walk-Away) Final Charge (Subtotal + Tip + Tax) Release Remaining Hold Restaurant Payout (T+2 Stripe / T+1 Finix)

Split Payment Engine

Even Split

Total ÷ N people. Each person is charged their equal share as a separate transaction.

By Item

Items assigned to individuals. Each charged their items + proportional share of tax and tip.

Custom

Manual amounts per person. Validated against total to ensure full coverage before processing.

Important: All split calculations are validated server-side. The sum of all individual charges must equal the total (subtotal + tax + tip) before any charges are captured. Rounding differences are absorbed by the last payer.

3. Data Layer — MongoDB + Zod

Primary Database: MongoDB Atlas (managed, SOC2-certified, encrypted at rest AES-256).

Zod Schema Architecture

Zod schemas serve as the single source of truth for the entire data layer, generating TypeScript types, MongoDB validation rules, and OpenAPI specifications.

Zod Schemas TypeScript Types (z.infer) MongoDB Validation Rules OpenAPI 3.1 (zod-to-openapi) Scalar API Docs TypeScript SDK (optional) Validation Middleware

Example: User Schema

// Zod schemas are the single source of truth
// → Generate TypeScript types (z.infer<typeof schema>)
// → Generate MongoDB validation rules
// → Generate OpenAPI spec (via zod-to-openapi)

const UserSchema = z.object({
  _id: z.string(),
  phone: z.string().regex(/^\+[1-9]\d{1,14}$/),
  verified: z.boolean().default(false),
  dinoVerified: z.boolean().default(false),
  paymentMethods: z.array(PaymentMethodSchema),
  preferences: UserPreferencesSchema,
  createdAt: z.date(),
  updatedAt: z.date(),
});

type User = z.infer<typeof UserSchema>;

Collections

Collection Key Fields Indexes
users phone, verified, dinoVerified, paymentMethods phone (unique), createdAt
restaurants name, address, cuisine, ownerId, stripeAccountId ownerId, location (2dsphere)
menus restaurantId, categories, isActive restaurantId + isActive
menuItems menuId, name, price, modifiers, allergens, dietaryTags menuId + category, allergens
orders restaurantId, tableId, userId, items, status, total restaurantId + status, tableId
orderItems orderId, menuItemId, modifiers, specialInstructions, status orderId
payments orderId, userId, amount, tip, status, stripePaymentIntentId orderId, userId + createdAt
tables restaurantId, number, capacity, section, status restaurantId + number
sessions userId, restaurantId, tableId, preAuthId, active userId + active, tableId + active
staff restaurantId, userId, role, status restaurantId + role
Technical Note: All collections use MongoDB Atlas's built-in schema validation generated from Zod schemas at deploy time. The zod-to-mongo-schema utility converts Zod definitions to MongoDB $jsonSchema validators, ensuring runtime data integrity matches compile-time types.

4. Real-Time Services

Technology Stack

Component Technology Purpose
WebSocket server Socket.io or ws Real-time order updates, table status, KDS updates
Push notifications Firebase Cloud Messaging (FCM) Order status, payment confirmations, payback reminders
Location services QR-based check-in (MVP) Link diner to table. Future: BLE / geofencing

WebSocket Events

Event Direction Payload
order:new Diner → Restaurant { orderId, tableId, items[] }
order:status Restaurant → Diner { orderId, status, estimatedTime }
table:status Restaurant → All { tableId, status }
kds:update Restaurant → KDS { orderId, items[], priority }
payment:complete System → Both { paymentId, amount, status }
Technical Note: WebSocket connections are authenticated via JWT and scoped to restaurant rooms. Diners join a room when they scan the table QR code. Kitchen staff subscribe to their restaurant's KDS channel. Reconnection is handled automatically with exponential backoff.

5. AI Processing Layer

Menu Parsing Pipeline

Upload (PDF/Photo) OCR Google Vision / Textract LLM Extraction Claude / GPT-4 Structured Menu Data Allergen Auto-Classification Confidence Scoring Human Review Queue

Allergen Classification Detail

Category Tags Detection Method
Allergens Gluten, Dairy, Nuts, Shellfish, Soy, Eggs Ingredient analysis via LLM
Diet Categories Vegetarian, Vegan, Pescatarian, Keto, Halal, Kosher Ingredient + preparation analysis
Confidence Levels High (>90%) Medium (70–90%) Low (<70%) LLM confidence scoring
Human Review Items below 90% confidence Flagged in RestaurantAIAllergenReview screen

AI Cost Tracking

Metric How Tracked
Per-request OCR cost Log each Vision/Textract call with image size + cost
Per-request LLM cost Log input/output tokens, model used, compute cost
Per-restaurant spend Aggregate costs by restaurant_id
Monthly totals Dashboard aggregation with budget alerts at 80% / 100%
Budget controls Per-restaurant monthly limit, global monthly limit
Model abstraction Pluggable provider layer for OCR + LLM swapping
Important: All AI operations are logged with full cost attribution. The pluggable provider layer enables switching between OCR engines (Google Vision vs. AWS Textract) and LLMs (Claude vs. GPT-4) without code changes, using environment-based configuration.

6. SOC 2 Compliance Features

Security Controls

Feature Implementation Status
Encryption at rest MongoDB Atlas AES-256 default + AWS KMS / GCP KMS for customer key management MVP
Encryption in transit TLS 1.2+ enforced on all connections MVP
Field-level encryption MongoDB CSFLE for PII (card tokens, phone numbers, addresses) MVP
Access control RBAC with least-privilege: separate DB users for API, admin, analytics MVP
Audit logging All data access events logged: who, what, when, from where MVP
Key rotation Automated 90-day key rotation schedule MVP
Penetration testing Annual third-party pen test Post-MVP
Data retention Defined retention periods per data type, automated purging MVP
Incident response Documented procedures for security incidents MVP

RBAC Roles

Role Access Level
api_service Read/write to operational collections (orders, payments, sessions)
admin_service Full access to all collections
analytics_readonly Read-only access to aggregated data, no PII
restaurant_owner Read/write own restaurant data only
kitchen_staff Read orders for own restaurant, update order status
Technical Note: RBAC enforcement happens at two layers: MongoDB database-level users with scoped privileges, and application-level middleware that validates JWT role claims against endpoint requirements. All role assignments and changes are audit-logged.

7. API & Documentation

REST API: Express.js or Fastify with OpenAPI 3.1 spec as the source of truth. All endpoints validated at runtime using Zod middleware.

Schema-to-API Pipeline

Zod Schemas
  → zod-to-openapi
    → OpenAPI 3.1 Spec
      → Scalar API Docs       (interactive explorer)
      → TypeScript SDK         (optional, auto-generated)
      → API Validation         (runtime middleware)

Why Scalar over ReadMe

Feature Scalar (Free) ReadMe ($99+/mo)
Cost Free (open-source, self-hosted) $99–299/mo
API Playground Best-in-class "Try It" Good
OpenAPI Support Native Native
Dark Mode Built-in Built-in
Customization Full (self-hosted) Limited
Self-Hosted Yes No

API Endpoints Summary

Group Endpoints Auth
Auth POST /auth/verify-phone
POST /auth/verify-code
POST /auth/refresh 		Public / JWT
Users GET /users/me
PUT /users/me
POST /users/me/payment-methods 		JWT
Restaurants CRUD /restaurants
GET /restaurants/nearby 		JWT / Public
Menus CRUD /restaurants/:id/menus
POST /menus/ai-upload 		JWT (restaurant)
Orders POST /orders
GET /orders/:id
PUT /orders/:id/status 		JWT
Payments POST /payments/pre-auth
POST /payments/charge
POST /payments/split 		JWT
Tables GET /restaurants/:id/tables
PUT /tables/:id/status 		JWT (restaurant)
KDS GET /restaurants/:id/kds
PUT /kds/:orderId/status 		JWT (kitchen)
Analytics GET /restaurants/:id/analytics/daily
GET /analytics/menu 		JWT (owner)
AI POST /ai/parse-menu
GET /ai/costs 		JWT (admin)
Technical Note: All API responses follow a consistent envelope: { success: boolean, data?: T, error?: { code, message } }. Rate limiting is enforced per-user (100 req/min for authenticated, 20 req/min for public endpoints) using Redis-backed sliding window counters.

8. POS Integration Layer POST-MVP

Component Description MVP Status
Toast API adapter Menu sync, order injection, payment reconciliation Post-MVP
Clover API adapter Menu sync, order injection, payment reconciliation Post-MVP
Square API adapter Menu sync, order injection, payment reconciliation Post-MVP
Menu sync service Bi-directional menu sync with POS Post-MVP
Note: MVP operates in standalone mode. POS integration is Phase 2. The adapter pattern is designed now so the integration layer can be plugged in without architectural changes.

9. Infrastructure & Deployment

Component Technology Justification
API Server Node.js (Express or Fastify) Team familiarity, TypeScript native
Database MongoDB Atlas (M10+ for production) SOC2 certified, managed, flexible schema
Cache Redis (ElastiCache or Upstash) Session cache, rate limiting
File Storage AWS S3 or GCP Cloud Storage Menu images, receipts, uploads
CDN CloudFront or Cloudflare Static assets, image delivery
Hosting Railway (MVP) → AWS/GCP (production) Fast iteration for MVP
CI/CD GitHub Actions Automated testing + deployment
Monitoring Datadog or Sentry Error tracking, APM, alerts

Architecture Overview

CLIENT LAYER Diner App (React) Restaurant App KDS Display API LAYER Node.js API (Express/Fastify) + WebSocket Server SERVICES Auth (Twilio) Payments (Stripe) AI (LLM/OCR) Push (FCM) Storage (S3) Cache (Redis) DATA LAYER MongoDB Atlas (SOC2 / AES-256 / CSFLE)
Technical Note: MVP uses a monolithic Node.js server deployed on Railway for rapid iteration. The codebase is structured with clear service boundaries (auth, payments, orders, AI) so individual services can be extracted into microservices when scaling demands it post-MVP.

10. MVP Scope Boundaries

IN Scope (MVP)

  • ✓ Phone + SMS verification (Twilio)
  • ✓ Card tokenization via Stripe (primary) or Finix (secondary) — 2.9% + $0.30
  • ✓ Pre-authorization holds and auto-settlement
  • ✓ QR code table check-in
  • ✓ MongoDB Atlas with Zod schemas (single source of truth)
  • ✓ WebSocket real-time updates (order status, KDS, table status)
  • ✓ AI menu parsing (OCR + LLM) with cost tracking and budget controls
  • ✓ AI allergen/dietary auto-classification with confidence scores and human review
  • ✓ SOC2-ready: encryption at rest, TLS, audit logging, RBAC, key rotation
  • ✓ API documentation via Scalar (free, self-hosted OpenAPI explorer)
  • ✓ Push notifications (FCM)
  • ✓ REST API with OpenAPI 3.1 spec

OUT of Scope (Post-MVP)

  • ✗ Carrier-based identity verification (use phone/SMS)
  • ✗ POS integration (Toast / Clover / Square — Phase 2)
  • ✗ BLE / geofencing location detection (use QR codes)
  • ✗ Advanced analytics pipeline
  • ✗ Multi-region deployment
  • ✗ Custom SDK generation
  • ✗ GraphQL API (REST only for MVP)
  • ✗ Microservices architecture (monolith for MVP)

Related Scope Documents

Diner App
Diner App MVP Scope

Consumer-facing mobile experience: onboarding, ordering, payments, and social features.
Restaurant App
Restaurant App MVP Scope

Restaurant dashboard, KDS, menu management, AI tools, and analytics.
You Are Here
Platform MVP Scope

Shared infrastructure, backend services, data layer, and compliance.