SalesArck Documentation

This documentation reflects the code that exists today in salesarck-monorepo.

What is SalesArck?

SalesArck is a multi-tenant loyalty platform with three current runtime apps:

• apps/api for the Hono backend and scheduled jobs
• apps/web for the React portal used by consumers, merchants, POS operators, and admins
• apps/workers as a scaffold for future background processing

The shared packages carry the actual domain logic: auth helpers, tenant resolution, RBAC, reward calculation, observability, and the Drizzle schema.

---

Start Here

Code Documentation

Canonical implementation docs for runtime behavior, routes, schema, and shared packages.

System Architecture

Current relationships between API, web, workers, shared packages, and external services.

Data Model

Current tables, constraints, and migration history from the Drizzle schema.

POS Integrations

Square and Clover OAuth, webhook handling, polling fallback, and normalization flow.

Reward Engine

Pure points calculation and redemption eligibility rules.

Authentication

Supabase auth, profile resolution, and role derivation.

API Reference

Current REST route groups and the behaviors they expose.

Merchant Onboarding

What the current merchant flow does from signup to POS connection.

Consumer Flow

Wallet, history, offers, redemption, and marketing preferences.

---

Current Stack

Property	Value
Primary Stack	Node.js 20, TypeScript, Hono, React 18, Vite, Supabase, Drizzle
POS Providers	Square and Clover
Auth	Supabase JWTs and OTP sign-in
Tenant Model	Server-derived tenant membership and URL-scoped tenant access
Rewards	Versioned reward rules with append-only ledger records
Deployment	Render for API, Cloudflare Pages for web
Background Work	In-process async webhook handling plus cron endpoints

---

Roles

Consumer ─── Earns and redeems points across merchant wallets
Client   ─── Merchant operator: configures rules, views analytics, manages POS
Admin    ─── SalesArck platform operator: global access, fraud controls, support

---

Core Guardrails

Security rules that must never be broken

1. Tenant identity is resolved server-side from JWT claims and URL tenant IDs.
2. Write paths that touch payment or reward state are protected by idempotency or DB uniqueness.
3. Wallet ledger history is append-only.
4. Admin actions write immutable audit logs.
5. Tenant-scoped queries must filter by tenant_id.

---

Developer Summary

The implementation treats POS as an input source, not the system of record. The API owns tenant resolution, reward calculation, wallet mutation, and auditability. The frontend mostly renders data already shaped by the backend, and the shared packages hold the actual domain rules.