System Architecture Overview
This overview reflects the current implementation in salesarck_code.
Runtime Components
API Composition
apps/api/src/app.ts wires middleware and route groups:
/api/v1/auth/api/v1/consumer/api/v1/client/api/v1/admin/api/v1/webhooks/api/v1/oauth/api/v1/internal/cron
Global middleware order:
- secure headers
- CORS
- correlation ID
- DB context attachment
- request logger
- route guards
Security Boundary Model
Identity
Supabase verifies bearer token identity server-side.
Authorization
SalesArck computes role and tenant membership from internal tables.
Tenant Isolation
Tenant context is derived from URL parameter + server-side claims, never body/query payload.
Permission Model
RBAC permissions are explicit and route-attached.
Data and Domain Model
Core domains in PostgreSQL:
- users and tenant membership
- POS connections and raw webhooks
- transactions and reward rules
- wallets and append-only ledger
- reward events and idempotency keys
- admin audit logs
See Data Model and Migrations for full schema details.
Event Processing Architecture
Fallback/backfill path:
- cron ->
/api/v1/internal/cron/square-poll-payments - iterates active Square merchants
- applies same ingestion workflow
Frontend Architecture
Single web app serves all personas through route guards and role-based navigation.
Key characteristics:
- PKCE callback recovery routing
- profile state fetch with retries and coalescing
- onboarding gating for merchant users
- API-backed pages for admin/client/consumer workflows
Operational Architecture Notes
- Sentry initialization occurs at API startup.
- Pino logger redacts common PII fields.
- Every API response includes
X-Correlation-Id. - Worker app exists as scaffold for durable queue-based async phase.
Canonical Deep Dives
Written byDhruv Doshi