SalesArck Documentation
Version 2.0 · Multi-Vendor Loyalty & Rewards Platform
SalesArck is a multi-tenant loyalty SaaS that ingests POS transaction data from Square and Clover, computes rewards using SalesArck-owned business logic, and delivers earn/redeem experiences for consumers across many merchants — all with strict tenant isolation and a financial-grade audit trail.
Quick Navigation
📌 Project Tracker
Live status: shipped surface, in-flight work, known gaps. Cross-checked against the monorepo.
🎯 Product Vision
Goals, scope, success criteria and the why behind SalesArck.
🗓 Roadmap & Phases
Phase 0 → Phase 3 delivery plan, team structure and DoD.
🏗 System Architecture
End-to-end architecture diagrams and component responsibilities.
🧠 Code Documentation
Implementation-level docs for runtime behavior, integrations, schema, and quality.
🗄 Data Model
Full ER diagram, table definitions, and wallet ledger design.
🔌 POS Integrations
Square & Clover OAuth, adapters, and webhook ingestion.
⚙️ Reward Engine
Rules, formulas, versioning and decision flow.
🔐 Authentication
Supabase Auth, JWT sessions, role resolution.
📡 API Reference
All REST endpoints across Auth, POS, Wallet and Admin.
📊 Observability
Logging, metrics, alerting and SLO tracking.
🔒 Security
Security controls, RBAC, compliance considerations.
🚀 Merchant Onboarding
Step-by-step guide: signup → POS connect → first reward.
🛡 Admin & Fraud
Admin fraud intervention, manual adjustments, audit logs.
Platform at a Glance
| Property | Value |
|---|---|
| Tenancy Model | Multi-tenant, software-level isolation |
| POS Providers | Square (Payments API + Webhooks), Clover (REST + Webhooks) |
| Auth Method | Supabase Auth OTP (mobile + email), no passwords |
| Reward Model | Points-per-spend, configurable per tenant |
| Transaction Ingestion | Webhook-first ≤ 60s, poll fallback ≤ 5min |
| Ledger Pattern | Append-only, double-entry inspired |
| Accuracy Target | ≥ 99.99% reward calculation accuracy |
| Primary Stack | Node.js / TypeScript, Hono, React, Supabase Postgres, Drizzle ORM |
| Deployment | Render (API) + Vercel (Web) + scheduler-driven poll fallback |
| Environments | local · dev · staging · prod |
Three User 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
Non-Negotiable Guardrails
- Never trust tenant identity from the client UI — always derive server-side from JWT
- Critical mutation and ingest paths must be idempotent — enforce dedup keys + DB constraints
- Reward events are append-only — never mutate historical ledger entries
- All admin actions generate immutable audit logs with actor, reason, before/after state
- No cross-tenant data leakage — tenant middleware enforced on every query
TL;DR for Developers
Build a strict multi-tenant loyalty platform where POS is a read-only data source. Treat reward and wallet state like financial data: append-only ledger + full auditability. Prioritize idempotency, tenant isolation, and observability before feature breadth. Use enterprise-capable managed services with free starter tiers, and plan for Supabase OTP/SMS delivery cost.