Deployment & Infrastructure

Current Topology

Deployment Targets

Surface	Platform	URL	Notes
API	Render	salesarc-api.onrender.com	Node + Hono; env validated at startup
Web	Vercel	salesarc-web.vercel.app	SPA with client-side routing rewrites
Docs	Cloudflare Pages	salesarck-documentation.pages.dev	Docusaurus static site
Workers	—	Not yet deployed	Scaffold only (apps/workers)

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

Cron and Async Strategy

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

Scheduled jobs run via external cron (Render cron, cron-job.org, or GitHub Actions) calling protected API routes:

Route	Suggested cadence	Purpose
POST /api/v1/internal/cron/square-poll-payments	every 5 min	ListPayments poll fallback for Square
POST /api/v1/internal/cron/process-pending-webhooks	every 5 min	Retry sweeper for stuck webhook events (both providers)

Both routes require X-Cron-Secret header.

Environment Contract

Backend env validation is codified in apps/api/src/lib/env.ts (Zod, exits on failure).

Group	Variables
Database	DATABASE_URL
Auth	SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY
Square	SQUARE_APP_ID, SQUARE_APP_SECRET, SQUARE_ENVIRONMENT, SQUARE_WEBHOOK_SIGNATURE_KEY
Clover	CLOVER_APP_ID, CLOVER_APP_SECRET, CLOVER_ENVIRONMENT, CLOVER_WEBHOOK_SECRET
Encryption	ENCRYPTION_KEY (64 hex chars)
URLs	API_BASE_URL, FRONTEND_URL
Ops	CRON_SECRET, SENTRY_DSN, LOG_LEVEL, RESEND_API_KEY, RESEND_FROM_EMAIL

Deployment Guardrails

1. Never reuse production Supabase project in non-prod environments
2. Keep webhook URLs and signature keys environment-specific
3. Validate Square and Clover *_ENVIRONMENT values match the credentials before OAuth testing
4. Rotate secrets through deployment platform secret stores
5. Run lint/typecheck/test before deploy promotion
6. Confirm ENCRYPTION_KEY is set before configuring any POS OAuth

Deep Dives

• Deployment and Environments
• API Reference