Roadmap & Delivery Phases
Delivery Timeline Overview
Phase 0 Phase 1 Phase 2 Phase 3+
Foundation MVP Core Stabilization Growth
2–3 weeks 6–8 weeks 3–4 weeks Ongoing
[────────────][───────────────][────────────────][──────────→
Auth POS + Ingestion Reconciliation Campaigns
RBAC Reward Engine Load testing Tiers
Tenants Wallet Ledger Observability White-label
Admin seed Consumer UI Runbooks More POS
Implementation status
Phase 0 ✅ complete · Phase 1 ✅ complete · Phase 2 🔧 in progress · Phase 3+ 🗓 planned
Phase 0 — Foundation ✅ Complete
Goal: Create the skeleton every team member builds on top of.
Deliverables
| Task | Owner | Notes |
|---|---|---|
| Monorepo setup (apps + packages structure) | Backend lead | Turborepo or Nx preferred |
| CI/CD pipeline (GitHub Actions) | DevOps | Lint → Test → Build stages |
| Environments provisioned (dev, staging, prod) | DevOps | Separate DB per env |
| Supabase Auth integration | Backend | Mobile + email OTP, single login flow |
| User model + RBAC middleware | Backend | Role claim validation, tenant middleware |
| POS Operator role setup | Backend | Limited role for redemption verification only |
| Tenant model + server-side tenant resolver | Backend | Never trust client-stated tenantId |
| Admin bootstrap | Backend | Seed script + env-config admin creation |
| DB migration tooling | Backend | pgmigrate or Drizzle |
| Basic logging + error tracking | Backend | Sentry + structured logs |
Phase 0 Done Criteria
- Any developer can clone the repo and run locally in < 10 min
- Supabase auth flow works end-to-end in dev environment
- Single web app login works for consumer, client, and admin users
- RBAC route gating works in UI and server-side checks remain authoritative
Phase 1 — MVP Core ✅ Complete
Goal: A merchant can onboard, connect POS, and their customers start earning and redeeming real points.
Deliverables
| Task | Owner | Priority |
|---|---|---|
| Square OAuth connect + disconnect | Backend | P0 |
| Clover OAuth connect + disconnect | Backend | P0 |
| Webhook endpoint + HMAC verification | Backend | P0 |
| Raw payload persistence | Backend | P0 |
| Transaction normalization pipeline | Backend | P0 |
| Idempotency layer (keys + dedup) | Backend | P0 |
| Consumer identity resolution | Backend | P0 |
| Reward engine v1 (points-per-spend) | Backend | P0 |
| Rule versioning | Backend | P1 |
| Wallet ledger + reward event writes | Backend | P0 |
| Wallet snapshot sync | Backend | P0 |
| Poll fallback job (Square) | Backend | P1 |
| Poll fallback job (Clover) | Backend | P1 |
| Consumer wallet / history UI | Frontend | P0 |
| Merchant reward config UI | Frontend | P0 |
| Merchant transaction dashboard | Frontend | P0 |
| Admin fraud flags + basic controls | Backend + Frontend | P1 |
| Token refresh background job | Backend | P0 |
Phase 1 Done Criteria
- Merchant can onboard in < 15 minutes
- Real Square transaction generates real wallet credit within 60s
- Consumer can view balance and redeem points
- Admin can see all tenants and basic fraud events
Phase 2 — Stabilization 🔧 In Progress
Goal: Make the MVP production-grade: reliable, observable, and battle-tested.
Deliverables
| Item | Status |
|---|---|
Webhook retry sweeper (process-pending-webhooks) | ✅ Shipped |
| Admin search + approval UI | ✅ Shipped |
| Manual wallet adjustment + freeze/unfreeze | ✅ Shipped |
| Store operator invite + management | ✅ Shipped |
| Reconciliation job (nightly POS vs ingested) | 🔴 Not started |
| Idempotency TTL cleanup job | 🔴 Not started |
| Performance testing at 10k txns/day | 🔴 Not started |
| Alerting expansion (webhook failure, queue lag) | 🔴 Not started |
| Runbooks for top 5 failure modes | 🔴 Not started |
| Clover poll fallback | 🔧 Gap — sweeper covers retry |
Phase 3+ — Growth Features 🗓 Planned
Campaigns Engine
- Time-windowed earn multipliers (e.g., "2x points on Fridays")
- Event-triggered bonus points (e.g., first purchase, birthday)
- Merchant self-serve campaign creation
Loyalty Tiers
- Bronze / Silver / Gold tiers with configurable thresholds
- Tier-based earn rate escalation
- Tier downgrade logic after inactivity or spend threshold drop
Point Expiry Automation
- Configurable TTL per tenant (e.g., points expire after 12 months inactive)
- Expiry preview and consumer notification sequences (30d, 7d, 1d warnings)
- Bulk expiry cron job with ledger debit entries
White-Label
- Per-tenant branding overrides (logo, color scheme, app name)
- Tenant-scoped subdomain or path routing
POS-Integrated Redemption (Deferred)
- Square Discount API — Programmatically apply loyalty discounts to the active order via Square’s Orders API, eliminating the manual discount step at the register
- Clover Discount API — Same capability via Clover’s Discounts REST API
- Toast POS — Toast’s API does not support programmatic discount creation; Option B is incompatible with Toast merchants
- QR Code Redemption — Consumer shows QR code, merchant scans to auto-confirm redemption. Deferred because web-only scanning is impractical (laptops lack cameras); revisit with native apps
- Gift Card / Store Credit — Load redemption value onto Square Gift Cards or Clover store credit for native POS payment (evaluate ROI before committing)
Additional POS Integrations
- Toast POS
- Lightspeed
- Shopify POS
Team Structure
| Role | Count | Responsibilities |
|---|---|---|
| Backend Lead | 1 | Architecture decisions, code review, complex service implementations |
| Backend Developer | 2 | Feature implementations, API work, migrations |
| Frontend Lead | 1 | Component architecture, API integration patterns |
| Frontend Developer | 1 | UI implementation, consumer + client portals |
| QA / Automation | 1 | Test coverage, E2E suites, regression management |
| DevOps (shared) | 0.5 | CI/CD, infra provisioning, monitoring |
| PM / Founder | 1 | Requirements, acceptance, prioritization |
Definition of Done (Per Feature)
Every feature is considered done only when all of the following are true:
□ API contract documented (endpoint, request/response shape, errors)
□ Unit tests passing with adequate coverage (domain logic ≥ 80%)
□ Integration tests passing (DB transactions, idempotency, RBAC)
□ Security check: tenant isolation verified, input validation in place
□ Monitoring: key metrics and log events instrumented
□ Feature flag added if change is risky or phased
□ Migration note added if DB schema changed
□ PR reviewed and approved by tech lead
□ Deployed to staging and smoke-tested
Written byDhruv Doshi