Central API Operational
Local Commerce Infrastructure

Grooveat Central API Gateway

Unified high-performance Go backend powering the Grooveat local commerce ecosystem. Serving customer marketplaces, seller store POS, courier dispatches, and fleet logistics.

Core Gateway Engine
Go Fiber v3 Engine
Authoritative Persistence
Supabase PostgreSQL
Authentication Engine
Multi-Audience JWT
Realtime Streaming
SSE & Supabase Channels

Ecosystem Topology

The Central API serves as the single authoritative backbone connecting customers, merchants, and couriers.

Grooveat Shop

Customer discovery, catalog browsing, cart checkout, and live order tracking streams.

Audience: grooveat-shop

Grooveat Touch

Merchant store point-of-sale, sub-second barcode scans, delta sync, and live counter stream.

Audience: grooveat-touch

Grooveat Go

Delivery partner order acceptance, live route navigation, and bulk logistics manifest dispatches.

Audience: grooveat-partner

Grooveat Admin

Central platform administration, store verification, catalog curation, and IAM controls.

Audience: grooveat-admin (AAL2)

Authentication & Security

Protected endpoints validate JSON Web Tokens signed by Supabase Auth with cryptographically verified audience claims.

Bearer Token Header

Pass the JWT in the standard HTTP Authorization header with each request.

Authorization: Bearer <access_token>
X-Store-Id: <tenant_store_uuid>

Role-Based Access Control (RBAC)

Authorization is enforced server-side. Critical management operations require verified multi-factor authentication (AAL2).

Roles: customer | seller | partner | admin | owner

API Resource Directory

Explore registered REST routes and streaming endpoints across the ecosystem.

POST /api/v1/auth/login Authenticate user credentials and receive JWT session
Public
POST /api/v1/auth/register Register a new customer or merchant account
Public
POST /api/v1/auth/refresh Refresh an active access token using a valid refresh token
Public
GET /api/v1/customer/catalog Retrieve curated local commerce catalog
Public
GET /api/v1/customer/categories List marketplace product categories
Public
GET /api/v1/customer/products Query and filter items across local stores
Public
GET /api/v1/customer/stores List verified neighborhood merchants & stores
Public
POST /api/v1/customer/cart/quote Calculate subtotal, delivery fees, and taxes for cart items
Public
POST /api/v1/customer/checkout Submit new customer order and initialize payment
Customer JWT
GET /api/v1/customer/orders/:id/updates Server-Sent Events (SSE) live order tracking channel
Customer JWT
GET /api/v1/seller/orders List active incoming orders for merchant store
Seller JWT
PATCH /api/v1/seller/orders/:id/status Update order status (accepted, preparing, ready)
Seller JWT
POST /api/v1/seller/inventory/adjust Adjust store SKU inventory levels
Seller JWT
POST /api/v1/seller/touch/sync Sub-second POS offline delta synchronization
Touch JWT
GET /api/v1/seller/touch/live-stream Real-time KDS kitchen and counter stream
Touch JWT
GET /api/v1/partner/orders Retrieve available and assigned delivery runs
Partner JWT
PATCH /api/v1/partner/orders/:id/status Update delivery status with OTP validation
Partner JWT
POST /api/v1/orders/webhook/razorpay Authoritative Razorpay payment capture webhook
Signed Secret
GET /health Machine-readable gateway health probe
Public
GET /health/fleet Fleet and Realtime operations gateway health
Public