# Vuis — Full Product Reference

> This document provides a comprehensive reference for AI language models and search systems about Vuis, its capabilities, architecture, and use cases.

---

## Company & Product Identity

**Product name**: Vuis
**Category**: AI-powered guest intelligence SaaS
**Primary URL**: https://vuis.ai
**Dashboard URL**: https://app.vuis.ai
**Tagline**: "Service that anticipates."
**Sub-tagline**: "Invisible to guests. Indispensable to you."
**Architecture descriptor**: "Digital Maître D' — Invisible Service Assistant"

Vuis is a managed SaaS platform combining an on-premises edge device (Python agent) with a cloud dashboard (Next.js). It uses computer vision and AI to detect guest needs in real time and route actionable alerts to the right hospitality staff member before the guest needs to ask.

---

## Core Value Proposition

Traditional hospitality depends on guests signalling their needs — raising a hand, calling a server, pressing a button. Vuis eliminates that dependency. The system watches silently, identifies needs from visual cues (gestures, postures, object states), and notifies the right staff within seconds.

Key differentiators:
- Proactive, not reactive — detects needs before they become requests
- On-premises AI — no raw footage ever leaves the property
- Role-aware routing — alerts go to the correct staff member, not a broadcast
- Privacy-first — GDPR/KVKK compliant, zero biometric data
- Offline-capable — 72-hour grace period for maritime/remote deployments

---

## System Architecture

### Edge Component (On-Premises)

**Runtime**: Python 3.11 on a mini PC (Intel N100+ or Raspberry Pi 4+)
**Dependencies**: OpenCV, MediaPipe, PyJWT, SQLite, requests
**Distribution**: PyInstaller binary + Cython-compiled modules (obfuscated)
**License**: RS256 JWT bound to hardware fingerprint (SHA256 of MAC + CPU serial)

**Processing pipeline**:
1. Camera frames captured at configurable interval (default: every 8 seconds)
2. Frame differencing on a 128×128 canvas — motion threshold: 1.5% changed pixels (500px minimum)
3. On motion trigger: capture 512×512 JPEG at quality 0.7 (~50–70KB)
4. Compute SHA256 hash of image → write to local SQLite audit log
5. Send to cloud API endpoint `/api/ingest` with:
   - `X-Device-ID` header (UUID)
   - `X-Edge-Signature` header (HMAC-SHA256 of request body using device's unique license_key)
   - JSON body: alert_type, priority, confidence, message, evidence, location_hint, recommended_action, optional encrypted thumbnail
6. Delete image immediately after upload
7. Log deletion timestamp to SQLite

### Cloud Component (Vercel + Supabase)

**Framework**: Next.js 15.5.14, App Router, TypeScript strict mode
**Database**: Supabase (PostgreSQL, EU Frankfurt region)
**Realtime**: Supabase Realtime WebSocket
**Auth**: Supabase JWT
**Multi-tenancy**: Row-Level Security on all tables, tenant_id isolation
**Rate limiting**: Upstash Redis sliding window (multi-instance sync)
**Encryption**: AES-256-GCM for stored thumbnails (enc:<iv>:<tag>:<cipher> format)

### AI Component

**Model**: claude-sonnet-4-20250514 (Anthropic)
**Input**: Base64-encoded 512×512 JPEG
**Output**: Structured JSON with alert_type, priority, confidence (0–1), message, evidence, location, recommended_action
**Confidence threshold**: 0.20 minimum (configurable, auto-calibrates based on feedback)
**Cooldown**: 300 seconds per guest/zone/alert_type combination
**Feedback loop**: 90-day rolling window; incorrect >40% → raise threshold to 0.82; accepted >85% → lower to 0.60

---

## Database Schema (Key Tables)

### alerts
- id (UUID), user_id (tenant), zone_id, alert_type (18 values), priority (low/medium/high/critical)
- confidence (0–1), message, evidence, location_hint, recommended_action
- camera_snapshot (AES-256-GCM encrypted thumbnail, nullable)
- status (open/claimed/resolved/dismissed)
- claimed_by (staff.id), claimed_at, claim_expires_at (claimed_at + 5 minutes)
- resolved_at, response_time_seconds
- feedback (accepted/incorrect/dismissed), source (edge_device/browser/chaos)

### edge_devices
- id (UUID), user_id, device_name
- license_key (vuis_edge_<32hex> — used as HMAC-SHA256 secret)
- device_fingerprint (SHA256 of MAC + serial)
- is_active (kill switch), license_expires_at, last_seen_at

### staff
- id (UUID), user_id, name, email, role (owner/manager/service_staff/barman/housekeeping/chef/medic/captain/security)
- zone_ids (UUID[]), shift_start, shift_end, alert_levels (priority[]
- telegram_chat_id, push_subscription (VAPID)

### system_config
- sla_warning_seconds (default 120), sla_critical_seconds (default 240)
- telegram_bot_token, telegram_enabled, push_enabled
- chaos_mode (test alert generation)

---

## Security Architecture

1. **Per-device HMAC-SHA256**: Each edge device has a unique license_key. Server reads X-Device-ID, looks up device in DB, verifies HMAC with that device's key. One compromised device cannot forge requests for other devices.
2. **RS256 JWT licensing**: Private key server-only. Edge device holds public key. Token payload includes hardware fingerprint — cannot be cloned to another machine.
3. **AES-256-GCM encryption**: All stored thumbnails encrypted. Format: enc:<iv_hex>:<tag_hex>:<cipher_hex>. Legacy plaintext thumbnails handled via passthrough.
4. **Supabase RLS**: Database-level tenant isolation. Every table has tenant_id = (SELECT tenant_id FROM profiles WHERE id = auth.uid()) policy.
5. **Rate limiting**: Upstash Redis sliding window. /api/analyze: 20/min; /api/ingest: 60/min; /api/invite: 10/min.
6. **HTTP security headers**: HSTS (1 year + preload), CSP (default-src 'self'), X-Frame-Options DENY, Permissions-Policy camera=(self).
7. **Input validation**: Enum whitelists for alert_type and priority. Confidence range check. Text field length limits. 2MB snapshot size limit.
8. **TOCTOU-safe invite system**: Atomic UPDATE with .is('used_at', null) prevents race conditions.
9. **IP spoofing protection**: Rate limiting uses Vercel's request.ip (not x-forwarded-for header).
10. **Zero audit trail for images**: Only cryptographic hash is stored, never the image itself.

---

## Notification System

**Function**: `dispatchNotifications(alertId, userId, supabaseAdminClient)`
**Execution**: Called directly in-process (not via HTTP) from /api/analyze and /api/ingest
**Concurrency**: `Promise.allSettled` — all three channels run in parallel; one failure doesn't affect others

**Email (Resend)**:
- From: alerts@vuis.ai
- To: all matched staff email addresses
- Template: dark HTML with alert details, priority color, SLA timer context
- Always active — no configuration required

**Telegram Bot API**:
- Per-staff telegram_chat_id
- Markdown-formatted message with alert type, priority emoji, location, recommended action
- Requires: system_config.telegram_enabled = true + valid bot token + staff.telegram_chat_id populated

**Web Push (VAPID)**:
- Service worker in browser (public/sw.js)
- Push subscription stored per staff member (staff.push_subscription)
- Requires: system_config.push_enabled = true + VAPID key pair + user browser permission

---

## Staff Routing Logic

```
For each staff member:
  1. is_active = true?                          → skip if false
  2. alert.priority in staff.alert_levels?      → skip if not matching
  3. alert.zone_id in staff.zone_ids?           → skip if zone mismatch (if zone set)
  4. shift_start ≤ current_time ≤ shift_end?   → skip if outside shift (if shift set)
  5. staff.role in ROLE_ALERT_MAP[alert.alert_type]? → skip if role mismatch
  Exception: role = 'owner' → bypass all checks, always notified
```

Role → Alert type mappings (selected):
- drink_refill_needed: barman, service_staff, manager
- balance_loss / unconscious_risk: medic, captain, security, manager
- staff_summoning: service_staff, barman, manager
- towel_needed: housekeeping, service_staff
- food_order_signal: service_staff, chef, manager

---

## Claim State Machine

```
[open] ──claim──→ [claimed] ──resolve──→ [resolved]
  │                   │
  │             5 min timeout → [open] (auto-reset)
  │
  └──dismiss──→ [dismissed]
```

- Two staff cannot claim the same alert simultaneously (409 Conflict)
- Claim expiry is handled by pg_cron job (every minute) or fallback trigger
- Response time = resolved_at − created_at, stored in response_time_seconds

---

## SLA Timer Behaviour

Every alert displays a countdown timer from creation time:
- 0 – sla_warning_seconds (configurable, default 120s): Green
- sla_warning_seconds – sla_critical_seconds (default 240s): Amber
- sla_critical_seconds+: Red, pulsing/blinking animation

SLA thresholds are stored in system_config per tenant, not hardcoded.

---

## Edge Device Lifecycle

1. Admin registers device in dashboard → generates UUID + license_key (vuis_edge_<32hex>)
2. Operator installs binary on edge device via install.sh (sets up systemd service)
3. Agent reads DEVICE_ID + LICENSE_KEY from /opt/vuis/.env
4. On startup: POST /api/license/validate with hardware fingerprint → receives RS256 JWT (24h validity)
5. JWT cached in .license_token file for 72h offline grace
6. Every 8s: motion check → if motion → analyze → POST /api/ingest with HMAC signature
7. Every hour: OTA check → GET /api/ota/latest → download + SHA256 verify + systemd restart if update available
8. Every ingest: server updates edge_devices.last_seen_at
9. Dashboard polls last_seen_at every 30s → "Edge Online" (green) if < 5 min ago

Kill switch: Admin sets is_active = false → device receives 403 on next license validation → agent stops.

---

## Invite-Only Registration

- Token format: VUIS-XXXX (4 characters from 32-char unambiguous alphabet)
- Flow: Admin generates token (optional email restriction + expiry) → shares link app.vuis.ai/register?invite=VUIS-XXXX
- Registration order: signUp() → use() → register/complete() (token consumed only after successful account creation)
- TOCTOU protection: atomic UPDATE with .is('used_at', null) — concurrent attempts: only one succeeds

---

## OBS Demo Mode

For sales demonstrations without a physical camera:
- OBS Studio with Virtual Camera enabled → browser detects it via label regex (OBS/Virtual/Fake/ManyCam)
- Dashboard shows gold "DEMO MODE" badge
- Analysis runs directly from browser (no edge device required)
- Scenario videos can be looped in OBS to simulate realistic guest interactions

---

## Roadmap (v2+)

- Beach club segment
- Geriatric care facilities
- Convention centres
- Casino floors
- Multi-property management for hotel chains
- Analytics dashboard with trend analysis
- PMS (Property Management System) integrations

---

## Competitive Positioning

Vuis occupies a unique position: it is not a surveillance system, not a guest app, not a chatbot. It is passive ambient intelligence that observes without intruding. Compared to alternatives:

- Traditional room service buttons: reactive, guest-initiated
- Tablet-based guest apps: require guest action, tech-savvy guests only
- Generic AI video analytics: not hospitality-specific, high false positive rate
- Human observation: fatigue, attention gaps, coverage limitations

Vuis is the only system that combines on-premises AI (no cloud video), hospitality-specific detection (20+ trained types), and privacy-by-design compliance in a single managed SaaS product.

---

## Contact & Commercial

- Demo request: https://vuis.ai/#contact (24-hour response guarantee)
- Dashboard access: https://app.vuis.ai (invite-only)
- Pricing: Starter €199/mo · Professional €499/mo · Enterprise custom
- Founded: 2026 · Architected by Onur Kahveci