Architecture Overview

Staccato Coffee follows a modern mobile architecture with a native iOS frontend, Supabase backend, and Square payment integration.

System Diagram

Customer browses menu → MenuService fetches from menu_items table
Customer adds to cart → CartViewModel manages state, persists to UserDefaults
Customer checks out → CheckoutViewModel orchestrates payment
Payment processed → SquarePaymentService calls process-payment Edge Function
Order created → OrderService inserts into orders, order_items, order_item_modifiers
Stars awarded → OrderService.awardStars() updates loyalty_accounts
Order synced → OrderService.syncToSquare() calls sync-square-order Edge Function

Order arrives → Supabase Realtime pushes to OrderQueueViewModel
Employee claims → OrderQueueService.claimOrder() sets assigned_to and status to in_progress
Order ready → OrderQueueService.markReady() sets status to ready
Order completed → OrderQueueService.completeOrder() sets status to completed

Decision	Rationale
MVVM Architecture	Clean separation of UI and business logic, native SwiftUI pattern
Singleton Services	Shared state management, single Supabase client instance
Direct Supabase Access	No middleware API needed — RLS handles authorization
Edge Functions for Square	Keeps Square API keys server-side, runs on Supabase infrastructure
UserDefaults for Cart	Lightweight persistence, survives app restarts
Idempotency Keys	Prevents duplicate payments and orders on retry
Non-blocking Square Sync	Order succeeds even if Square sync fails