System Architecture Overview
This overview reflects the code currently present in salesarck-monorepo.
Runtime Components
API Composition
apps/api/src/app.ts wires middleware and route groups:
/api/v1/auth/api/v1/consumer/api/v1/pos(POS operator code verification)/api/v1/client/api/v1/marketing/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 and route-specific middleware
Security Boundary Model
Identity
Supabase verifies bearer token identity server-side. The API uses the service-role client only on the server.
Authorization
SalesArck computes role, approval status, and tenant membership from internal tables and verified JWT claims.
Tenant Isolation
Tenant context is derived from URL parameter plus server-side claims, never body/query payload.
Permission Model
RBAC permissions are explicit and route-attached. The current matrix covers consumer, POS operator, client, and admin permissions.
Data and Domain Model
The current schema includes:
- users and tenant membership + operator invites
- POS connections and raw webhooks
- transactions and reward rules + reward events
- wallets, append-only ledger, and redemption codes
- idempotency keys, admin audit logs, marketing preferences, and merchant campaigns
See Data Model and Migrations for full schema details.
Event Processing Architecture
Recovery paths:
- Square poll fallback:
POST /api/v1/internal/cron/square-poll-payments— paginatesListPayments, same ingestion pipeline. - Clover poll fallback:
POST /api/v1/internal/cron/clover-poll-payments— lists payments modified since the Clover watermark, same ingestion pipeline. - Webhook retry sweeper:
POST /api/v1/internal/cron/process-pending-webhooks— retries Square and Clover jobs the immediate webhook pass did not finish. - Campaign sweeper:
POST /api/v1/internal/cron/process-campaigns— sends queued campaign recipients in batches. - Wallet reconciliation:
POST /api/v1/internal/cron/reconcile-wallets— records snapshot drift against the ledger sum. It does not rewrite ledger rows.
Frontend Architecture
Single web app (apps/web) serves all four personas through layered route guards and role-based navigation shells.
Key characteristics:
- PKCE callback recovery routing.
- Profile state fetch with retries and coalescing.
- Onboarding gating for merchant users until the merchant setup flow is complete.
- API-backed pages for admin/client/consumer/pos_operator workflows.
- Supabase session storage in the browser.
Operational Architecture Notes
- Sentry initialization occurs at API startup.
- Pino logger is used through
@salesarc/observability. - OAuth tokens for Square and Clover are encrypted at rest.
- Tenant logos and campaign media are stored in Supabase Storage.
- Worker app (
apps/workers) exists as a scaffold for future durable async work.