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

---

Phase 0 — Foundation (2–3 weeks)

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 (6–8 weeks)

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 + 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 (3–4 weeks)

Goal: Make the MVP production-grade: reliable, observable, and battle-tested.

Deliverables

• Reconciliation job — nightly comparison of POS records vs ingested transactions
• Idempotency hardening — stress test and fix edge cases in replay scenarios
• Performance testing — load test against realistic merchant volume (10k txns/day/tenant)
• Alerting expansion — webhook failure, token refresh burst, queue lag
• Runbooks — documented playbooks for top 5 failure modes
• Access review — audit all admin actions since Phase 1 go-live
• Support tooling — admin search, replay tools, manual adjustment UI

---

Phase 3+ — Growth Features (Ongoing)

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