Spaces:
Running
Running
| 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 | |
| ```bash | |
| 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: | |
| ```bash | |
| 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. | |