Order System

Orders flow from cart checkout through preparation, delivery, and payment settlement.

Order Creation

Orders are created in handlePay() in src/app/cart/page.tsx:

1. Validate address coordinates and delivery distance
2. Find or create delivery address record
3. Create order via createOrder() repository function
4. Add each cart item via addOrderItem()
5. Process payment (cash: immediate placed, card/PayPal: pending_payment)
6. Send push notification to restaurant staff

Key fields set at creation:

• user_id — customer’s Supabase auth UID
• restaurant_id — resolved from cart
• address_id — delivery address
• delivery_address_snapshot — full address frozen at order time
• fulfillment_type — delivery or pickup
• estimate_prep_minutes — from restaurant’s default_prep_minutes
• delivery_distance_km — haversine distance to restaurant
• scheduled_for — ISO timestamp for future orders (null = ASAP)
• All cost fields (subtotal, tax, delivery fee, service fee, tip, discount, total)

Order Statuses

Valid Status Transitions

pending_payment → placed, accepted, canceled
placed          → accepted, canceled
accepted        → ready, canceled
ready           → out_for_delivery, canceled
out_for_delivery → delivered, canceled
delivered       → payment_received
payment_received → provider_paid
provider_paid   → (terminal)
canceled        → (terminal)

Each transition updates a corresponding timestamp field (accepted_at, ready_at, picked_up_at, delivered_at, etc.).

Push Notifications

Notifications sent via sendPushNotification() in src/lib/pushManager.ts. Uses APNs (iOS) and FCM (Android) with interruption-level: time-sensitive for reliable delivery.

Scheduled Orders

• Customer selects “Schedule” mode instead of “ASAP”
• Must be 60+ minutes in the future, within 7 days
• Must fall within restaurant open hours
• Stored in scheduled_for field (ISO timestamp)
• Cron job (/api/cron/order-reminders) sends reminders to staff when scheduled orders approach their time (15-minute window)

Driver Assignment

Two methods:

1. Driver claims: Views available orders at /api/driver/orders/available, claims via POST /api/driver/orders/{id}/claim
2. Admin assigns: PATCH /api/admin/orders/{id} with driver_user_id

Max active deliveries per driver is configurable via DRIVER_MAX_ACTIVE_DELIVERIES env var (default: 1).

Discount Codes

• Applied at order creation via create_order_with_discount RPC function
• Validated via /api/cart/validate-discount before checkout
• Types: percentage (% off) or amount (fixed cents off)
• Constraints: max claims, start/end dates, restaurant-specific or platform-wide

Key Files