Deployment & Infrastructure

Current Topology

Environment Model

Environment	Purpose	Auth/DB	POS credentials
local	developer iteration	local or sandbox Supabase	sandbox
dev	shared integration	separate dev Supabase project	sandbox
staging	pre-prod validation	separate staging Supabase project	sandbox
prod	live traffic	separate production Supabase project	production

Deployment Targets

API

• runtime: Node + Hono (apps/api)
• deploy target: Render service
• startup: env validation -> Sentry init -> app start

Web

• runtime: React + Vite (apps/web)
• deploy target: Vercel
• depends on Supabase public keys and API base URL

Workers

• current status: scaffold (apps/workers)
• planned role: queue consumers and scheduled background jobs

Cron and Async Strategy

Webhook path uses fast-ack + async processing in API process.

Fallback/backfill route:

• POST /api/v1/internal/cron/square-poll-payments
• secured by X-Cron-Secret

This supports reliability before full queue-worker rollout.

Environment Contract

Backend env validation is codified in apps/api/src/lib/env.ts.

Important variables include:

• database: DATABASE_URL
• auth: SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY
• square: SQUARE_APP_ID, SQUARE_APP_SECRET, SQUARE_ENVIRONMENT, SQUARE_WEBHOOK_SIGNATURE_KEY
• encryption: ENCRYPTION_KEY
• urls: API_BASE_URL, FRONTEND_URL
• ops: CRON_SECRET, SENTRY_DSN, LOG_LEVEL

Deployment Guardrails

1. never reuse production Supabase project in non-prod environments
2. keep webhook URLs and signature keys environment-specific
3. validate Square environment and host alignment before OAuth testing
4. rotate secrets through deployment platform secret stores
5. run lint/typecheck/test before deploy promotion

Deep Dives

• Deployment and Environments
• API Reference