Single-tenant web2app funnel system: ad click → quiz → results → paywall → embedded Solidgate checkout → success. Server-verified purchases fan out to Meta CAPI + Amplitude. Admin console handles funnel lifecycle, visual editing, versioned deployments, A/B experiments, themes, integrations, and activity logging.
cp .env.example .env.local # already set to mock/log defaults
npm install
npm run seed # seeds funnel + products + theme into .data/firestore.json
npm run dev
- Public funnel: http://localhost:3000/f/archetype
- Admin console: http://localhost:3000/admin (email
you@example.com, passwordletmeinfrom.env.local) - Visual editor: click Edit ✎ on any funnel row →
/editor/<funnelId>/<variantId>
npm run test # vitest — schema, conditions, HMAC vectors, A/B distribution
npm run typecheck # tsc --noEmit
14 unit tests, everything green.
Every integration is env-gated. Flip one at a time as credentials arrive.
| Var | Values | Behavior |
|---|---|---|
DB_MODE |
mock | live |
Mock persists to .data/firestore.json; live uses Firebase Admin SDK. |
SOLIDGATE_MODE |
mock | live |
Mock renders MockPaymentForm (Approve/Decline/Duplicate); live uses @solidgate/react-sdk + @solidgate/node-sdk. |
SOLIDGATE_ENV |
sandbox | production |
Which Plan.productIds is used at checkout. Orthogonal to SOLIDGATE_MODE. |
META_MODE |
log | live |
Server-side Purchase → Meta CAPI. log prints exact payload. |
AMPLITUDE_MODE |
log | live |
Server-side Purchase → Amplitude HTTP V2. log prints exact payload. |
NEXT_PUBLIC_ANALYTICS_MODE |
log | live |
Client-side Pixel + Amplitude. log prints to console. |
npm run seed && npm run dev- Open
/f/archetype— walk through quiz, email, results, paywall. - Pick a plan → checkout screen → Approve payment (mock).
- Mock form signs a webhook with dev keys and POSTs
/api/webhooks/solidgate— the handler runs its full production code path (HMAC verify, idempotency, upsert, CAPI + Amplitude fire). - Inspect
.data/firestore.json:sessions/<sid>→status: "purchased",answers,email,variantId.subscriptions/<orderId>→status: "approved",entitlement,flowType,reportedValue,events[],conversionStatus: "sent".processed_events/<eventId>→ dedupe marker.activity_log/<ulid>→ every admin action.
- Watch the terminal for
[meta_capi:log]and[amplitude_http:log]Purchase payloads withevent_id === orderId,external_id = SHA-256(sessionId), value fromreportedValue. - Click ↻ Re-send last webhook to test idempotency →
deduped: true, no double-fire.
Do these in order. Each step is independently reversible (flip the env var back).
- Create a Firebase project + enable Firestore in native mode.
- Create a service account with
Cloud Datastore Userrole; download JSON. base64 -i sa.json | tr -d '\n'→ paste asFIREBASE_SERVICE_ACCOUNT_B64in.env.local.- Install Firebase CLI:
npm i -g firebase-tools, thenfirebase login+firebase use <projectId>. - Deploy rules + indexes:
npm run db:deploy(runsscripts/setup-firestore.sh). - Verify TTL is enabled on
processed_events.expiresAt— the deploy script prints the fallbackgcloudcommand if the indexes.json TTL directive didn't stick. - Flip
DB_MODE=live. Runnpm run seedonce to populate the live project. - Optional: run
npm run db:emulatorlocally to smoke-test without touching prod.
- From the Solidgate Hub, grab the four keys and load them:
SOLIDGATE_API_PUBLIC_KEY=api_pk_... SOLIDGATE_API_SECRET_KEY=api_sk_... SOLIDGATE_WEBHOOK_PUBLIC_KEY=wh_pk_... SOLIDGATE_WEBHOOK_SECRET_KEY=wh_sk_... - Point the Solidgate Hub's webhook URL at
https://<host>/api/webhooks/solidgate. - Sync the Products mirror (
/admin/products) with your Solidgate product catalog — either edit the seed list inscripts/seed.tsor add rows in Firestore directly. - Serve Apple Pay's association file: paste the file contents into
/admin/settings?tab=domains→ the app auto-serves it at/.well-known/apple-developer-merchantid-domain-association. - Add Solidgate outbound IPs to any WAF/allowlist in front of
/api/webhooks/solidgate. - Flip
SOLIDGATE_MODE=live(keepSOLIDGATE_ENV=sandboxfor testing first). - Complete a sandbox purchase end-to-end → subscription doc + verified webhook + CAPI/Amplitude Purchase.
- Flip
SOLIDGATE_ENV=productionwhen ready.
- Meta Ads Manager → get the Dataset ID (formerly Pixel ID) and a Conversions API access token.
- Amplitude → get a client-side API key (browser) and a separate server-side key (HTTP V2).
- Load:
NEXT_PUBLIC_META_PIXEL_ID=<dataset id> META_PIXEL_ID=<same dataset id> META_CAPI_ACCESS_TOKEN=<token> NEXT_PUBLIC_AMPLITUDE_API_KEY=<browser key> AMPLITUDE_SERVER_API_KEY=<server key> AMPLITUDE_REGION=us # or eu - Flip
META_MODE=live,AMPLITUDE_MODE=live,NEXT_PUBLIC_ANALYTICS_MODE=live. - In Meta Events Manager → Test Events, complete a sandbox purchase. Confirm a single
Purchaseevent with the correct value + dedup key. - In Amplitude → Live Event Stream, confirm client events (
funnel_start,screen_view, …) and the server-sidepurchaseevent both show up under the sameuser_id.
- In your DNS provider, point the custom domain (e.g.
quiz.prayers.academy) at Vercel via CNAME. - Enter the custom domain in
/admin/settings?tab=domains. - Confirm
/.well-known/apple-developer-merchantid-domain-associationreturns 200 with the Solidgate-supplied contents.
Ad (Meta) ──▶ /f/[slug] ──assign variant──▶ quiz (element renderer)
│ events → Amplitude + Pixel
▼
results ──▶ paywall ──▶ checkout (Solidgate)
│
client success = UX only
│
Solidgate ──webhook──▶ /api/webhooks/solidgate ──▶ verify HMAC ─▶ write subscription
└▶ fire Purchase → Meta CAPI + Amplitude
Key rule: the client is never the source of truth for a payment. A purchase is only "real" when the verified webhook says so.
app/f/[slug]/page.tsx # public funnel (RSC, picks variant, renders FunnelRunner)
app/api/sessions/* # server-only session CRUD
app/api/solidgate/init/route.ts # signed payment init (mock or live via gateway factory)
app/api/webhooks/solidgate/route.ts # raw-body HMAC verify → idempotency → upsert → server conversions
app/api/dev/simulate-webhook # mock-mode only signer/poster
app/admin/ # console: funnels, editor, experiments, deployments, themes,
# customers, products, subscriptions, integrations,
# settings (general/domains/team/api-keys), activity
app/editor/[id]/[vid]/page.tsx # visual builder (FunnelFox-style layout)
app/.well-known/… # Apple Pay verification file
lib/config/schema.ts # zod schema assembled from element registry
lib/elements/registry.ts # single source of truth: type → props schema, defaults, category
lib/elements/*.tsx # per-element runtime components
lib/renderer/ # FunnelRunner + Screen/ElementRenderer + RuntimeContext
lib/editor/ # FunnelEditor + Canvas + panels + property forms
lib/state/funnelStore.tsx # React context + useReducer + sessionStorage persistence
lib/analytics/ # client bus + adapters (console/Amplitude/Pixel)
# server senders (Meta CAPI, Amplitude HTTP, log)
lib/payments/ # gateway factory · Solidgate sign/webhook/mock ·
# SolidgatePaymentForm.tsx (real @solidgate/react-sdk)
# MockPaymentForm.tsx (dev-only)
lib/ab/assignVariant.ts # deterministic weighted pick
lib/db/ # DbAdapter (mock ↔ firebaseAdapter) + domain modules
lib/auth/adminAuth.ts # shared-password gate (Phase A) — Firebase Auth wiring later
firestore.rules # deny-all client access; admin SDK bypasses
firestore.indexes.json # composite indexes + TTL on processed_events.expiresAt
firebase.json # emulator config + deploy targets
scripts/setup-firestore.sh # one-time deploy of rules/indexes + TTL command hint
scripts/seed.ts # seed funnel + products + theme
scripts/simulate-webhook.ts # CLI webhook signer
Everything the FunnelFox screenshots show is in — full account console, visual
canvas editor, integrations, activity log, themes, products mirror. Cancellation
funnel type is modeled but the trigger wiring from subscription management
is Phase 2 (not scoped here). The client's existing www.prayers.academy app
is the handoff target after success.