Buyer Journey Simulator

Live URL: ppc.io/buyer-journey-simulator Shared results: ppc.io/buyer-journey-simulator/r/[id] (noindex)

What It Does

Free tool that takes any website URL, scrapes it, extracts business context + buyer personas via Claude, then simulates each persona’s complete purchase journey in first person. Outputs gap analysis, competitor switch detection, and a full Google Ads playbook with per-persona media plans.

Architecture

Framework: Astro 6 (SSR, prerender = false) + React 19 (client:only="react")
Hosting: Cloudflare Workers via @astrojs/cloudflare adapter
AI: Claude Sonnet 4 via @anthropic-ai/sdk (server-side)
Scraping: Firecrawl REST API (server-side)
Storage: Cloudflare KV (SESSION namespace) for shareable results (30-day TTL)
Design: Dark zen aesthetic matching swipe-wall design system

File Map

API Routes (`src/pages/api/journey/`)

File	Method	Purpose
`scrape.ts`	POST	Takes URL, scrapes homepage + 4 subpages via Firecrawl, returns markdown
`extract.ts`	POST	Takes scraped content, Claude extracts business context + personas
`simulate.ts`	POST	Takes business + personas, Claude streams journey simulation via SSE
`save.ts`	POST	Saves results to KV, returns short ID for sharing
`load.ts`	GET	Loads saved results by ID

React Components (`src/components/JourneySimulator/`)

File	Purpose
`JourneyApp.tsx`	Root state machine - orchestrates all screens + API calls
`InputScreen.tsx`	URL input with 3 feature bullets (matches swipe-wall pattern)
`LoadingScreen.tsx`	Progress steps + orbital animation, two phases (scrape/simulate)
`ContextScreen.tsx`	Business intel review - positioning, competitors, trust signals, editable fields, extra context box
`JourneyScreen.tsx`	Timeline with color-coded stages, search terms, channel badges, ad hints per stage, sticky persona sidebar
`ResultsScreen.tsx`	3-tab dashboard: Persona Debrief, Google Ads Playbook (campaigns, keywords, ad copy, media plans, budget), Cross-Persona Summary
`UsageGateModal.tsx`	3-run limit modal with waitlist CTA
`types.ts`	All TypeScript interfaces
`useUsageGate.ts`	localStorage-based usage tracking (3 free runs)

Astro Pages

File	Purpose
`buyer-journey-simulator.astro`	Main page - CSS vars, atmosphere orbs, noise texture, scroll reveal
`buyer-journey-simulator/r/[id].astro`	Shared results page (noindex, nofollow)

User Flow

Input - Enter any URL (+ optional context)
Scrape + Extract - Firecrawl scrapes site, Claude extracts business context (loading: “Analyzing Business”)
Context Review - User sees positioning, competitors, trust signals, content gaps. Can edit classification fields and add extra context
Simulate - Claude builds personas + simulates journeys with streaming SSE (loading: “Simulating Journeys”)
Journey Timeline - Per-persona first-person narratives with color-coded stages:
- Awareness (amber) - Display Ads, YouTube
- Research (violet) - Search Ads, Blog Content
- Consideration (blue) - Retargeting, Case Studies
- Decision (green) - Brand Search, Call-Only
- Post-Purchase (red) - Review Requests, Loyalty
Results Dashboard - Three tabs:
- Persona Debrief (friction points, priorities, what worked)
- Google Ads Playbook (campaigns, keywords, ad copy, per-persona media plans, budget split)
- Cross-Persona Summary (universal gaps, competitor patterns, contradictions, #1 fix)
Export - Download JSON, share link (KV-backed, 30 days), run another simulation

Environment Variables

Both are set in wrangler.jsonc as vars (private repo):

Variable	Purpose
`ANTHROPIC_API_KEY`	Claude API (rate-limited key)
`FIRECRAWL_API_KEY`	Firecrawl scraping API

Deployment

cd ppc-io-frontend
npm run deploy   # builds + wrangler deploy

Requires wrangler login first (OAuth). Deploy is manual, not auto-triggered by git push.

Key Decisions / Gotchas

prerender = false - This page MUST be server-rendered (API routes need server-side env vars). Cannot be static.
not_found_handling: "none" in wrangler.jsonc - Changed from "single-page-application" because the SPA fallback was serving index.html (homepage) for SSR routes like this one. This was the deployment blocker that took multiple attempts to diagnose.
client:only="react" - React components hydrate client-side only. An earlier approach using manual createRoot in a <script> tag failed because Astro processes scripts differently.
Cache-Control: no-store - Set in middleware.ts for /buyer-journey-simulator* routes to prevent Cloudflare CDN caching SSR responses.
CSP connect-src - API calls to Firecrawl and Anthropic happen server-side (Worker), so no CSP changes needed for those domains.
Usage gate - localStorage-based, trivially bypassable. Just a soft gate for the free tool launch.
Streaming - The simulate endpoint uses SSE (Server-Sent Events) to stream Claude’s response. The client accumulates text chunks and parses the complete JSON when done. This is NOT progressive rendering - it just prevents timeout on long responses.

Design Tokens

Matches the swipe-wall design system:

Background: #0a0b10
Surface: #12141c
Violet: #a78bfa (primary accent)
Green: #34d399 (hits/success)
Amber: #fbbf24 (warnings/competitors)
Red: #fb7185 (gaps/issues)
Fonts: Figtree (body), Outfit (headings), Space Mono (labels)
Atmosphere: floating gradient orbs + SVG noise texture