README.md

metadata

title: Grabby Voice
colorFrom: green
colorTo: yellow
sdk: docker
app_port: 7860
fullWidth: true
pinned: false

Matcha Moments — frontend

Cafe-aesthetic, mobile-first PWA that walks a customer through a 5-clip guided video review and, on submit, hands them a matcha redemption code.

This repo is a standalone Next.js app. It calls Humeo's deployed public review APIs (https://humeo.app/api/public/reviews/*) — no backend changes needed in the Humeo monorepo for v1.

The original Humeo codebase lives at reference/ for type / pattern lookups. It's gitignored, so it never ships with this repo.

---

Tech stack

• Next.js 14 (App Router) + TypeScript + Tailwind CSS
• @ffmpeg/ffmpeg (ffmpeg.wasm) — client-side concatenation of the 5 recorded clips into one video before upload
• getUserMedia + MediaRecorder — standard browser camera APIs (no native install required)
• zod — shared validation schemas, mirrors the ones in Humeo's src/lib/reviews/types.ts

Why a PWA over Expo: the customer-facing flow has to start in a tabletop QR scan in a cafe. Asking the customer to install an app kills conversion. Browser-based flow opens in 2 seconds, no install, works on iOS Safari and Android Chrome.

---

What it does (5 screens)

1. / — QR landing context screen (dev-only; in prod, the cafe's QR deep-links straight to /c/[slug])
2. /c/[slug] — Cafe landing: brand, big "Free matcha, on the house" headline, consent copy, primary CTA
3. /c/[slug]/record — Guided 5-clip recorder (video preview → prompt card → record button → auto-advance)
4. /preview — ffmpeg.wasm stitches the clips, uploads to Humeo, polls submission status, shows the rendered preview
5. /reward — Confetti, reward code in a dark card, "show this screen to your server"

The [slug] route is a real Next.js dynamic segment that fetches its campaign from ${NEXT_PUBLIC_HUMEO_API_URL}/api/public/reviews/campaign/[slug], the same endpoint Humeo's existing public review flow already uses (reference/src/app/api/public/reviews/campaign/[slug]/route.ts).

---

Getting started

cp .env.example .env.local      # then edit NEXT_PUBLIC_HUMEO_API_URL if needed
npm install
npm run dev                     # http://localhost:3000

Test on your phone (recommended)

getUserMedia only works on https:// (or http://localhost). Easiest path:

npx ngrok http 3000

Then open the https://*.ngrok-free.app URL on your phone, scan the QR or load /c/sageandstone directly. iOS Safari and Android Chrome will prompt for camera and mic. Allow both.

---

How it talks to Humeo

matcha-moments PWA                   Humeo backend (deployed)
-----------------                    ------------------------
GET  /c/[slug]            ──────►    GET  /api/public/reviews/campaign/[slug]
                          ◄──────    { id, slug, restaurantName, rulesConfig, ... }

stitch clips locally (ffmpeg.wasm)

POST /preview submit      ──────►    POST /api/public/reviews/submit
                                       FormData: video, slug, consentAccepted,
                                                 deviceKey, durationSeconds, tableId
                          ◄──────    { submissionId, status, decision, reward }

poll every 6s             ──────►    GET  /api/public/reviews/submission/[id]?slug=...
                          ◄──────    { status, decision, feedback, reward }

src/lib/humeoApi.ts is the only place that fetches from humeo.app. If Humeo's review_campaigns row doesn't yet have mode / prompts / theme columns, getCampaign() augments the response with a hardcoded fallback prompts list — flagged with TODO so we drop it once the BE migration ships.

Fields Humeo's BE will eventually need

To remove the fallback, Humeo's review_campaigns schema would add:

• mode text — 'single_take' | 'guided_clips'
• prompts jsonb — array of { step, title, tip, camera, maxSeconds }
• theme text — 'default' | 'cafe-cream'

Until then the matcha-moments app silently injects the cafe defaults.

---

Why client-side ffmpeg.wasm?

Humeo's /api/public/reviews/submit accepts a single video file. We want a multi-clip guided UX without forking Humeo's submit flow. Stitching the 5 recordings in the browser solves that with zero backend changes.

Trade-offs:

• 8MB WASM download, lazy-loaded only after the customer finishes recording
• 3-6 seconds of stitch time on a modern phone for ~50s of total video
• next.config.js sets COOP/COEP headers (required for SharedArrayBuffer)

If cafe staff start hearing complaints about phone heat, swap to a multi-clip upload + server-side ffmpeg endpoint. Humeo's worker (reference/src/lib/server/processInterview.ts) already uses ffmpeg, so the migration is mostly a new submit endpoint.

---

Project layout

src/
  app/
    layout.tsx                    Fonts (Fraunces / DM Sans / DM Mono), global CSS
    page.tsx                      QR landing (dev-only)
    c/[slug]/
      page.tsx                    Server component — fetches campaign
      LandingClient.tsx           Cafe landing screen
      record/
        page.tsx                  Server component — fetches campaign
        GuidedRecordingClient.tsx 5-clip guided recorder
    preview/page.tsx              Stitch + upload + preview
    reward/page.tsx               Reward code reveal
    globals.css
  components/                     Button, MatchaCircle, ProgressPips, PromptCard,
                                  RecordButton, RecordingBadge, RenderShimmer,
                                  Confetti, RewardCard
  hooks/
    useGuidedRecording.ts         getUserMedia + MediaRecorder + hard cap
    useSubmissionPolling.ts       Mirrors Humeo's PublicReviewRecordingClient polling
  lib/
    humeoApi.ts                   Typed fetch wrapper for /api/public/reviews/*
    ffmpeg.ts                     ffmpeg.wasm concatClips() helper
    recordingStore.ts             In-tab clip store, useRecordingStore() hook
    utils.ts                      cn(), ensureDeviceKey()
    reviews/
      types.ts                    Zod schemas + types (mirrors Humeo's)
      public.ts                   Display helpers (verbatim from Humeo)
reference/                        Humeo's repo (gitignored, read-only library)
matcha-moments-prototype_2.html   Original wireframe (visual spec)

---

Out of scope (v1)

• Per-clip re-record (current "re-record" wipes all 5 — flagged as a known product call in matcha-moments-prototype_2.html dev notes)
• Email-me-a-copy of the final video
• Staff-side redemption screen
• Reward expiry / redemption tracking
• Native iOS/Android wrapping (Humeo can ship this as a Capacitor or PWA-installed shortcut later)

---

Deploying

Vercel — connect this repo, set NEXT_PUBLIC_HUMEO_API_URL=https://humeo.app, done. The COOP/COEP headers in next.config.js carry over on Vercel.

CORS: confirm humeo.app allow-lists this app's deploy domain (e.g. matcha.humeo.app) on the /api/public/reviews/* routes.