Skip to main content

March 2, 2026 — Architecture Kickoff

Date: Monday, March 2, 2026 Attendees: Dhruv, Ajay, Amitosh, Siddharth, Suraj, Mahima

Summary​

Dhruv presented the comprehensive technical architecture document covering system design, POS integration approach, reward engine, and database schema. Team aligned on key architectural decisions and identified the redemption flow as the primary open challenge.

Action Items​

  • Dhruv to verify OAuth support across all POS systems (99% confident but will double-check)
  • Dhruv to design the redemption flow for how POS systems will access customer point balances
  • Ajay and development team to review Dhruv's technical documentation and architecture proposal
  • Ajay, Suraj, and team to send questions and clarifications via email as soon as possible
  • Suraj to have a brief chat tomorrow evening (urgent items to discuss)
  • Mahima to document and send formal action items
  • Team to meet again tomorrow, Tuesday morning India time / Monday evening (same time as today)

Key Decisions​

Target POS Systems (Phase 1)​

Square, Clover, Shopify, Lightspeed, and Toast — all five have APIs available for integration.

Expected Scale​

20–30 vendors in the first year, with buffer planning for up to 100 clients.

Timeline​

Aggressive two-week POC target. Fail-fast philosophy — start development immediately rather than prolonged architectural discussions.

Platform Structure​

Single instance, multi-tenant with role-based authentication (admin, vendors, customers).

Technical Architecture Overview​

Core System Components​

LayerComponents
Client LayerConsumer web app, merchant portal, admin console
API GatewayCloudflare Workers with HONO (edge computing)
Core ServicesAuth, tenant resolver, RBAC, wallet, reward engine, POS integration, transaction ingestion, admin operations
Data LayerPostgres (Neon or Supabase), Redis cache, rate limiter, object storage, observability
DeploymentPrimary on Cloudflare Workers, fallback on Fly.io for hybrid approach

POS Integration Approach​

Authentication & Security:

  • OAuth 2.0 authentication flow for all POS systems
  • Vendors configure POS credentials (tenant IDs, client IDs, client secrets) directly in SalesArck
  • Credentials stored in secrets manager (Doppler, AWS Secrets Manager, or GitHub Action Secrets) — never in database
  • HMAC SHA-256 signature verification for webhook security

Data Synchronization — Two Methods:

MethodDescriptionDetails
Webhook (preferred)POS systems push transaction data to SalesArck endpointsSquare: 10 retries / 24h · Clover: 5 retries
Polling (fallback)Query POS APIs every 30–60 seconds for new transactionsWorst case: 500 req/min (100 vendors × 5 POS) — well within capacity

Both methods can be used simultaneously based on POS system capabilities.

Adapter Pattern:

  • Single POS integration microservice with adapter interface per POS system
  • Adding a new POS requires implementing a new adapter only — no re-architecture

Developer Access & Testing​

  • Developer accounts are straightforward to create (~3 minutes for Square)
  • Sandbox credentials available for all team members
  • Production vendors only need to enable API access, not developer accounts

Reward Engine Discussion​

Configuration Options Reviewed​

  • Spend-based rates (e.g., $10 = 1 point)
  • Minimum spend thresholds
  • Redemption minimums and caps per transaction
  • Campaign multipliers and time windows
  • Rule version control
  • Vendor-specific rewards (not centralized)

Outstanding Challenge: Redemption Flow​

Issue identified: How will POS systems know customer point balances to apply discounts at checkout?

  • Cannot post data back to POS via polling
  • Possible solution floated: convert rewards to coupons that can be sent to POS systems
  • Dhruv to research further and discuss with Amitosh and Siddharth offline
  • This component will be developed later in the project timeline, not in the first 1–2 days

Technical Details Confirmed​

  • Complete database schema provided in documentation
  • JWT token-based authentication following industry standards
  • POS connection state machine diagram included
  • Transaction flow sequence diagrams for all major operations
  • Monorepo structure with request lifecycle documentation

Discussion Notes​

  • Scaling concern dismissed: 500 API requests/minute worst case — any server handles this easily
  • Secret management: OAuth credentials stored in secrets manager, never in database (Doppler, AWS Secrets Manager, or GitHub Action Secrets)
  • Webhook vs. polling: Team leaning towards webhook for scalability but polling as failback; architectural trade-off to finalize
  • Microservices architecture: Changes to individual services don't require major refactoring
  • Developer access clarification: Sandbox/developer access is for internal testing only; production vendors just enable API access on their end
Last updated on
Written byDhruv Doshi