RepuShield · Project Map
Product

Flow

The end-to-end flows that make RepuShield work — each step shows what happens and which screen the user is on.

1 · Audit Flow (free analysis)

Trigger: User pastes a Google Business Profile URL/name on /audit

  1. 1
    Input + validate/audit

    Accepts maps.google.com, maps.app.goo.gl, g.page, raw Place ID, hex CID, coordinate-only URLs.

  2. 2
    Expand short URL/audit

    maps.app.goo.gl / share.google resolved to full form via redirects.

  3. 3
    Parse GBP URL/audit

    Extract Place ID / CID / business name — 8+ formats, no-throw decode.

  4. 4
    Rate limit/audit

    Anon 5/hr, logged-in 20/hr; 429 if exceeded.

  5. 5
    Background scrape/audit

    Job created; runBackgroundScrape() via ctx.waitUntil() survives disconnect (VPS Playwright / Outscraper).

  6. 6
    Tier classification/audit

    Each review scored Tier 1 (spam/profanity/off-topic), Tier 2 (incentivized/vague), Tier 3 (clean).

  7. 7
    Poll status (SSE)/audit

    queued → scraping → analyzing → complete, every 3s with 1s heartbeat.

  8. 8
    Result + upsell gate/audit/result/[jobId]

    Current vs projected rating, flagged reviews, revenue impact, package selector.

Key files
src/app/audit/page.tsxsrc/app/audit/result/[jobId]/page.tsxsrc/app/api/audit/start/route.tssrc/lib/parse-gbp-url.tssrc/lib/audit-rules.tssrc/lib/audit/background-scrape.ts

2 · Purchase & Fulfillment

Trigger: User clicks 'Buy Removal' on the result page (or subscribes to a tier)

  1. 1
    Pick package/audit/result/[jobId]

    Pay-per-removal $179/review, or Shield / Fortress / War Room subscription (monthly credits).

  2. 2
    Create checkout/portal/billing

    Verify email + rate-limit, then create LemonSqueezy or Polar.sh session.

  3. 3
    Pay(external)

    Hosted checkout (Merchant of Record handles tax/compliance).

  4. 4
    Webhook(server)

    order_created / subscription_created → idempotency guard → DB writes.

  5. 5
    Removal requests created/portal/removals

    One record per flagged review: violationCategory + status pending.

  6. 6
    Atomic credit consume(server)

    UPDATE … WHERE remaining > 0 RETURNING — no concurrent over-spend.

  7. 7
    Admin submits appeals/admin/reviews

    Pre-written Google appeal per category, bulk-submit.

  8. 8
    Status tracking/track/[trackingId]

    pending → submitted → resolved / failed; client follows via tracking page.

Key files
src/app/api/payments/checkout/route.tssrc/app/api/payments/webhook/route.tssrc/app/api/webhooks/polar/route.tssrc/lib/payments/*src/lib/credits-manager.tssrc/lib/webhook-idempotency.ts

3 · Cold Email / Outreach Engine

Trigger: Admin creates a campaign in /admin/campaigns (or runs /admin/marketing/launch)

  1. 1
    Discover businesses/admin/campaigns/new

    Filter by area, category, min rating; multi-source email discovery with waterfall fallback.

  2. 2
    Create campaign + targets/admin/campaigns/[id]

    Smart (AI) or standard; targets imported via CSV/JSON.

  3. 3
    AI generate + score(server)

    Claude writes variants; LLM-as-judge scores; Thompson-sampling variant selector.

  4. 4
    GDPR geo-block(server)

    EU/EEA/UK/CH targets skipped before queueing (compliance).

  5. 5
    Queue + warmup/admin/email-warmup

    Domain throttle, 8-week warmup ramp (5→50/day), bounce/complaint circuit breaker.

  6. 6
    Send 5-step sequence(server)

    Plain-text steps 1+4 (Primary tab), HTML 2/3/5 with case study + revenue card.

  7. 7
    Backoff on failure/admin/email-queue

    Retry +5m then +30m; 3rd failure → dead-letter (admin retryable).

  8. 8
    Reply handling/admin/inbox

    Inbound webhook classifies interested / not / question; stops sequence.

  9. 9
    Waterfall fallback(server)

    No reply after full sequence → switch to secondary email, fresh sequence.

Key files
src/app/api/admin/campaigns/[id]/execute/route.tssrc/app/api/admin/marketing/launch/route.tssrc/lib/email-queue.tssrc/lib/cold-email-wrapper.tssrc/lib/email-guards.tssrc/lib/waterfall-fallback.tssrc/lib/ai-email-generator.ts

4 · Auth & Billing Lifecycle

Trigger: User visits /register or /login

  1. 1
    Register/register

    Email+password or Google OAuth; trial starts, status on_trial.

  2. 2
    Verify email/verify-email/[token]

    Confirmation link; payment actions gated on verified email.

  3. 3
    Login + 2FA/login

    bcrypt credentials or Google; TOTP / backup code if enabled.

  4. 4
    Trial period/portal

    Unlimited audits; cannot purchase until verified / trial ends.

  5. 5
    Subscribe/portal/billing

    Webhook sets tier, billing cycle, firstPaidAt, clears trialEndsAt.

  6. 6
    Billing cycle/portal/billing

    Failed payment → past_due; monthly credit refresh.

  7. 7
    Cancel/portal/billing

    Cancels via provider; status cancelled; trialEndsAt cleared so UI is honest.

Key files
src/auth.tssrc/app/api/auth/*src/app/api/portal/billing/cancel/route.tssrc/lib/credits-manager.ts

5 · Demo Pipeline

Trigger: Open /demo/play (marketing + LemonSqueezy approval video)

  1. 1
    Auto-play tour/demo/play

    Scripted walkthrough: audit input → analysis → tiers → pricing → subscribe.

  2. 2
    Demo data bank/demo/play

    Crafted reviews that trigger each tier (no live scrape).

  3. 3
    Capture/demo/play

    1920×1080 fullscreen; voice/face layered in post.

Key files
src/app/demo/play/page.tsxsrc/app/demo/play/DemoPlayer.tsxsrc/lib/demo-reviews.ts

6 · Admin Launch Mission Control

Trigger: Admin opens /admin/launch

  1. 1
    Sprint status/admin/launch

    Soft launch + hard launch targets, day counter.

  2. 2
    Blockers/admin/launch

    P0/P1 issues (LS approval, DNS, variant IDs).

  3. 3
    Daily checklist/admin/launch

    Task list across launch week with completion log.

  4. 4
    Activity timeline/admin/launch

    Events from launchActivityLog table.

Key files
src/app/admin/launch/page.tsxsrc/lib/launch-sprint-status.tssrc/components/admin/LaunchMissionControl.tsx