Skip to content

About

Prayers Academy — funnel runtime + admin

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Prayers Academy — Funnel Runtime

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.

Quick start (no external services required)

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

Testing

npm run test         # vitest — schema, conditions, HMAC vectors, A/B distribution
npm run typecheck    # tsc --noEmit

14 unit tests, everything green.

Modes matrix

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.

End-to-end mock verification

  1. npm run seed && npm run dev
  2. Open /f/archetype — walk through quiz, email, results, paywall.
  3. Pick a plan → checkout screen → Approve payment (mock).
  4. 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).
  5. 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.
  6. Watch the terminal for [meta_capi:log] and [amplitude_http:log] Purchase payloads with event_id === orderId, external_id = SHA-256(sessionId), value from reportedValue.
  7. Click ↻ Re-send last webhook to test idempotency → deduped: true, no double-fire.

Go-live checklist

Do these in order. Each step is independently reversible (flip the env var back).

1 · Firebase (persistence)

  1. Create a Firebase project + enable Firestore in native mode.
  2. Create a service account with Cloud Datastore User role; download JSON.
  3. base64 -i sa.json | tr -d '\n' → paste as FIREBASE_SERVICE_ACCOUNT_B64 in .env.local.
  4. Install Firebase CLI: npm i -g firebase-tools, then firebase login + firebase use <projectId>.
  5. Deploy rules + indexes: npm run db:deploy (runs scripts/setup-firestore.sh).
  6. Verify TTL is enabled on processed_events.expiresAt — the deploy script prints the fallback gcloud command if the indexes.json TTL directive didn't stick.
  7. Flip DB_MODE=live. Run npm run seed once to populate the live project.
  8. Optional: run npm run db:emulator locally to smoke-test without touching prod.

2 · Solidgate (payments)

  1. 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_...
    
  2. Point the Solidgate Hub's webhook URL at https://<host>/api/webhooks/solidgate.
  3. Sync the Products mirror (/admin/products) with your Solidgate product catalog — either edit the seed list in scripts/seed.ts or add rows in Firestore directly.
  4. 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.
  5. Add Solidgate outbound IPs to any WAF/allowlist in front of /api/webhooks/solidgate.
  6. Flip SOLIDGATE_MODE=live (keep SOLIDGATE_ENV=sandbox for testing first).
  7. Complete a sandbox purchase end-to-end → subscription doc + verified webhook + CAPI/Amplitude Purchase.
  8. Flip SOLIDGATE_ENV=production when ready.

3 · Analytics (Meta + Amplitude)

  1. Meta Ads Manager → get the Dataset ID (formerly Pixel ID) and a Conversions API access token.
  2. Amplitude → get a client-side API key (browser) and a separate server-side key (HTTP V2).
  3. 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
    
  4. Flip META_MODE=live, AMPLITUDE_MODE=live, NEXT_PUBLIC_ANALYTICS_MODE=live.
  5. In Meta Events Manager → Test Events, complete a sandbox purchase. Confirm a single Purchase event with the correct value + dedup key.
  6. In Amplitude → Live Event Stream, confirm client events (funnel_start, screen_view, …) and the server-side purchase event both show up under the same user_id.

4 · Domain

  1. In your DNS provider, point the custom domain (e.g. quiz.prayers.academy) at Vercel via CNAME.
  2. Enter the custom domain in /admin/settings?tab=domains.
  3. Confirm /.well-known/apple-developer-merchantid-domain-association returns 200 with the Solidgate-supplied contents.

Architecture map

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.

File map

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

Deferred (out of scope for this build)

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.

About

Prayers Academy — funnel runtime + admin

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages