Ribbit.Deals — Functional Specification

v1.0 · August 13, 2026 · Maintained alongside development — updated every sprint · Companions: Architecture · Data Layer · App UI

0. Purpose of This Document

This is the single running reference for what Ribbit.Deals does and why. It travels alongside development: every speed bump, question, and resolution lands here so decisions are made once and remembered forever. Anything marked LOCKED is founder-approved; RECOMMENDED is the team's position awaiting sign-off; OPEN needs a decision.

1. System Overview

Ribbit.Deals is a performance-based local deals platform for Utah, delivered as a Progressive Web App (no app stores) with a public marketing website. Local businesses publish offers; consumers discover them nearby and redeem them in person; redemption is verified by a two-factor handshake (GPS presence + placard scan); businesses pay a performance fee only on verified redemptions, alongside a one-time activation and a per-location operations fee.

• Platform: PWA (installable from browser) + responsive website · MySQL 8 data layer (deployed, v1.1) · PHP application layer (Sprint 6+).
• Environments: staging at ribbit.pixrite.com (current), production domain at launch.
• Core loop: business posts offer → consumer discovers → in-store verified redemption ("RIBBIT") → consumer earns rewards → business pays on results → loop repeats.

2. Audiences & Experience Isolation LOCKED

Two audiences, two completely separate experiences, one door between them.

• Consumer UX (default): home, For Deal Hunters, How It Works, Locator, About, Get the App, and the consumer app screens. Playful "Vegas" register; Yellowtail script accents permitted.
• Business UX: landing, enrollment, pricing, login, dashboard, offer creation. Professional register; no script font; no sunburst.
• The single door: the "I'm a Business Owner" button on consumer pages. The business UX contains zero links back to the consumer UX; its logo homes to the business landing page.
• Voice: business-side copy never uses the word "user" — owners are addressed as beneficiaries and partners. Consumers are "deal hunters."
• Enforcement: an automated link audit runs on every site update; consumer pages may reference the business UX only via the door, business pages may reference the consumer UX never. Current status: PASS across all 16 pages/screens.

3. Consumer Journey

3.1 Sign-up LOCKED

• Exactly four fields: name, mobile, email, password. Nothing else at sign-up; enrichment happens in-app after value is delivered.
• SMS deal alerts: explicit opt-in checkbox, unchecked by default, consent timestamp recorded (users.sms_opt_in_at), STOP/HELP honored.
• Privacy promise (founder language) displayed at sign-up: data used only by Ribbit.Deals to improve the service and by redeemed-at businesses to validate redemptions and improve offers; never sold.

3.2 Discovery

• Map-first with list toggle; offers sorted by distance; filters: category, distance radius. Featured placement slot exists (promotion rules: Phase 2).
• Website Locator mirrors discovery for pre-install visitors: A–Z, category, city filters + "Near Me" geolocation sort (haversine). Optionally reads live DB via read-only endpoint.

3.3 Redemption

See Section 5 — the verification handshake is the product's heart.

4. Business Journey

4.1 Enrollment LOCKED

• Five steps: Business → Locations → Pricing → Billing & Agreement → Confirmation. Progressive capture (each step saves; abandonment recoverable).
• Pricing is never published publicly; it is revealed at Step 3, computed from location count. (Gated-pricing rationale: pricing may evolve during early market entry; public numbers create anchor problems.)
• Step 4 records agreement acceptance: checkbox + typed legal name + timestamp + agreement version (subscriptions).
• Live within 24–48 hours of verification; placard kit printed and delivered as part of activation.

4.2 Dashboard

• Daily glance: views, redemptions, fees accrued. Per-location filter on all reporting.
• Offer controls: pause (one tap, instant), edit, per-offer stats. Recent redemptions list with Void action (Section 7).
• Month-to-date fee strip (operations + performance) always visible; statement generated on the 1st.

5. Redemption Verification — the Placard Handshake LOCKED

Two independent factors, no business-side hardware or software:

• Liveness screen ("RIBBIT"): animated frog + running real-time clock + word of the day — defeats screenshot reuse; a cashier verifies in two seconds by glancing at motion + clock.
• Trust valve: the business can void any redemption within 48 hours from the dashboard (Section 7); voided redemptions are never billed and reverse earned points.
• Failure paths: GPS unavailable → placard scan alone with elevated logging; camera unavailable → short code entry; both unavailable → redemption not possible (by design — verification is the product).

6. POS Integration — Decision Record RECOMMENDED: DO NOT INTEGRATE (v1)

Question raised (Aug 13 stakeholder meeting): should Ribbit.Deals integrate with common point-of-sale systems (Square, Clover, Toast, Lightspeed, …) to verify purchases at the register?

Team recommendation: no POS integration in v1. The placard handshake already delivers verified, in-person redemption without it. Integration would add:

What POS integration would buy: transaction-amount capture (basket size analytics) and marginally stronger purchase proof. Mitigations without it: the 48-hour void window handles no-purchase scans; basket analytics can be a Phase 2+ opt-in (e.g., receipt total entry or a single-platform pilot) if merchants demand it — decided from data, not speculation.

7. Offers, Caps & Void Rules LOCKED

• Offer anatomy: title, description, image, type (% / $ / BOGO / freebie), value, participating locations, geofence radius (100–2,000 m), schedule, max redemptions, budget cap.
• Caps are guarantees: enforced in the redemption write transaction (row-lock counter check); auto-pause the moment either cap is reached. The creation form shows the worst-case dollar figure live.
• One redemption per person per offer unless the offer states otherwise.
• Void window: 48 hours, dashboard action, reason optional; voids reverse points and are excluded from invoicing. Fee amounts are snapshotted per redemption (redemptions.performance_fee_amount) so historical bills never shift.

8. Rewards, Badges & Referrals LOCKED

• Points: earned on verified redemptions; append-only ledger (points_ledger) — balance is derived, adjustments are entries, history is immutable.
• Badges (v1 set, seeded): First Ribbit, Pond Hopper, Chorus Starter, Regular.
• Referrals: personal code; both parties rewarded when the referred person completes their first verified redemption; self-referral and duplicate-device abuse blocked.
• Earn rates and unlock thresholds: values OPEN — see Section 12.

9. Pricing & Billing Model LOCKED (structure) OPEN (amounts)

• Three components: one-time activation · per-location operations fee (monthly, or annual at a discount) · flat performance fee per verified redemption.
• Never published publicly; revealed at enrollment Step 3, computed from location count.
• Invoicing: monthly statement on the 1st; every performance line traces to a redemption record; one invoice line per redemption (unique constraint — double-billing is structurally impossible).
• Dollar amounts: required from founders before Sprint 7 billing work. Enrollment shows placeholders by design until then.

10. Privacy, Security & Non-Functional

• Location privacy: captured only at redemption moment; no background tracking. Stated in EULA §6 and Privacy Notice.
• Data promise: never sold; business sees a consumer's data only for redemptions at that business, for validation and offer improvement.
• Money handling: all currency stored as integer cents; payment card data never touches our servers (processor-hosted fields, Stripe planned).
• Auth: password hashing (bcrypt), rate-limited login, single shared auth for business web + dashboard (business_users pivot).
• Legal: EULA v0.2 (23 sections), Business Participation Agreement, Privacy Notice — drafted, awaiting Utah counsel; arbitration-vs-courts decision flagged for counsel + founders.
• Accessibility & motion: reduced-motion honored on all animations; focus states on all interactive elements.

11. Decision Log

12. Open Questions

13. Changelog