Technical Architecture

Overview

AdRecon V2 is a modern SaaS platform built with a Vercel-hosted static site frontend and Supabase-powered backend. The architecture prioritizes:

Direct frontend-to-database queries with row-level security (RLS)
Serverless API functions for media proxying, admin operations, and page capture
Single-page application (SPA) routing with authentication gating
Production-grade deployment workflow with staging and production branches

For complete implementation details, see docs/agent-reference.md in the source repository.

Stack Components

Frontend

Vite + React + TypeScript
Tailwind CSS for styling
Framer Motion for animations
Lucide React icons
Sonner for toast notifications

Backend

Supabase Postgres (views + tables with RLS)
Supabase Auth (Magic Link + Google OAuth)
Vercel Serverless Functions (Node.js)

Hosting

Vercel static site hosting
Vercel Edge Network for global distribution
SPA rewrites via vercel.json

Capture Pipeline

Puppeteer Core + @sparticuz/chromium
SingleFile for HTML snapshots
Archiver for ZIP packaging

Runtime Topology

Hosting Model

AdRecon is deployed as a Vercel static site built from the dist/ directory:

App Shell: app/index.html is served at both / and /app via Vercel rewrites
Build Output: Mirrors the SPA shell at dist/index.html and dist/app/index.html
Vite Entry Shim: app/src/main.tsx imports src/main.tsx to ensure /app works in both dev and production
Base Path: Vite uses / in dev and /app/ in production so assets resolve correctly

Route Architecture

Public Routes
Authenticated Routes
API Routes
Static Assets

/              → /app/index.html (SPA auth shell)
/index.html    → /app/index.html

/app                    → /app/index.html (Dashboard)
/app/:path*             → /app/index.html (SPA fallback)
/admin                  → /app/index.html (Admin Dashboard)
/admin/:path*           → /app/index.html
/admin/fanbasis         → /app/index.html (Fanbasis controls)
/profile                → /app/index.html (Profile settings)
/profile/:path*         → /app/index.html

/api/ad-media           → Serverless media proxy
/api/admin/users        → Admin user management
/api/admin/fanbasis     → Fanbasis admin actions
/api/fanbasis/webhook   → Fanbasis event webhook
/api/download-page      → Page Ripper endpoint

/app/assets/:path*      → Vite build output (JS, CSS, images)

SPA Routing Logic

The authentication gate in src/App.tsx determines which component renders:

Session Check

Supabase client (initialized in src/lib/supabase.ts) checks for an active session.

Unauthenticated State

If no session exists, render the <Auth> component (Magic Link + Google OAuth).

Authenticated Routing

For authenticated users, route to the appropriate view:

/admin or /app/admin: Render <AdminDashboard> if user.raw_app_meta_data.user_type === 'admin', otherwise show access warning
/admin/fanbasis or /app/admin/fanbasis: Render <FanbasisAdmin> (admin-only)
/profile or /app/profile: Render <ProfilePage>
All other routes: Render <Dashboard> (main ad feed interface)

Data Flow

Feed Query Architecture

AdRecon queries Supabase directly from the frontend using three feed scopes:

All Ads (Default)
Saved Ads
Project Ads

Data Source: public.ads_feed_v2

// src/lib/ads.ts
const { data, error } = await supabase
  .from('ads_feed_v2')
  .select('*')
  .order('created_at', { ascending: false })
  .range(offset, offset + limit - 1);

This normalized view aggregates raw data from public.apify_ads_raw with:

Fixed network classification (ClickBank, Digistore24, BuyGoods, MaxWeb, Other)
Fixed taxonomy classification (Health, Wealth, BizOpp, Relationship, Survival, Other)
High-quality media URL prioritization

Data Source: public.user_saved_ads_feed_v1

// src/lib/ads.ts
const { data, error } = await supabase
  .from('user_saved_ads_feed_v1')
  .select('*')
  .eq('user_id', userId)
  .order('saved_at', { ascending: false });

This view joins user_saved_ads with ads_feed_v2 and enforces RLS filtering by auth.uid().

Data Source: public.user_project_ads_feed_v1

// src/lib/ads.ts
const { data, error } = await supabase
  .from('user_project_ads_feed_v1')
  .select('*')
  .eq('project_id', projectId)
  .order('saved_at', { ascending: false });

This view joins user_saved_ad_projects → user_saved_ads → ads_feed_v2 and filters by project_id + auth.uid().

Saved Ads Persistence

Save Action

User clicks Save in the Ad Modal.

Database Insert

Frontend calls saveAd(userId, adArchiveId) from src/lib/savedAds.ts:

await supabase
  .from('user_saved_ads')
  .insert({ user_id: userId, ad_archive_id: adArchiveId });

Composite key (user_id, ad_archive_id) prevents duplicates.

RLS Enforcement

Supabase RLS policy ensures auth.uid() = user_id, isolating saved ads per user.

Project Management

Create Project

User creates a project via the Dashboard:

// src/lib/projects.ts
await supabase
  .from('user_projects')
  .insert({ user_id: userId, name: projectName });

Assign Ad to Project

User assigns a saved ad to one or more projects:

await supabase
  .from('user_saved_ad_projects')
  .insert({ user_id: userId, ad_archive_id: adId, project_id: projectId });

Query Project Feed

Dashboard queries user_project_ads_feed_v1 filtered by project_id.

Serverless API Functions

Media Proxy (`/api/ad-media`)

Purpose: Secure image proxy for ad creatives to avoid CORS and mixed-content issues. Implementation:

Vercel serverless function (api/ad-media.js)
Fetches external image URLs and returns the binary response
Passes through Content-Type headers
No authentication required (public endpoint)

Usage:

<img src="/api/ad-media?url=https://example.com/creative.jpg" />

Admin User Management (`/api/admin/users`)

Purpose: Admin-only endpoint for user CRUD operations. Implementation:

Vercel serverless function (api/admin/users.js)
Requires SUPABASE_SERVICE_ROLE_KEY for elevated database access
Validates admin status via auth.users.raw_app_meta_data.user_type
Supports creating, updating, and deleting users

This endpoint bypasses RLS and requires service role credentials. Admin status must be verified on every request.

Fanbasis Integration (`/api/admin/fanbasis`)

Purpose: Admin controls for Fanbasis product sync and webhook registration. Implementation:

Vercel serverless function
Requires FANBASIS_API_KEY, SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY
Admin-gated actions for:
- API health check
- Product list sync
- Webhook registration
- Offer enable/disable toggles

Fanbasis Webhook (`/api/fanbasis/webhook`)

Purpose: Receive and log Fanbasis payment events. Implementation:

Validates webhook signature using secret from public.integration_secrets
Logs events to public.fanbasis_webhook_log
Handles refund/dispute events by revoking user access

Page Ripper (`/api/download-page`)

Purpose: Inline landing page capture using headless Chromium. Implementation (api/download-page.js):

Request Validation

Authenticate user via Supabase session
Validate rate limit: 10 captures per user per 15 minutes (logged in page_rip_log)
Check SSRF safety: hostname blocklist + DNS verification

Headless Capture

Launch Puppeteer with @sparticuz/chromium
Navigate to target URL with 110-second AbortController timeout
Auto-scroll to trigger lazy-loaded content
Capture HTML using SingleFile
Intercept network resources (CSS, JS, images, fonts, media)

Resource Packaging

Package page.html + assets/ into a ZIP archive using archiver
Enforce caps: 100 MB total, 500 resources max

Response

Return ZIP binary directly in HTTP response
No storage bucket, no job queue — entire lifecycle in one request

Page Ripper runs on Vercel serverless infrastructure with a hard 120-second timeout. Captures typically complete in 15-45 seconds.

Database Schema

Core Tables and Views

public.apify_ads_raw

Type: TableRaw ad data ingested from Apify scrapers. Source table for ads_feed_v2.RLS: Enabled, authenticated role has read access.

public.ads_feed_v2

Type: ViewNormalized ad feed with:

Fixed network classification
Fixed taxonomy classification
High-quality media URL prioritization
Consistent schema for UI consumption

Queried by: Dashboard (all scope)

public.user_saved_ads

Type: TablePer-user saved ads with composite key (user_id, ad_archive_id).RLS: auth.uid() = user_id for strict user isolation.Used by: Save/unsave operations (src/lib/savedAds.ts)

public.user_projects

Type: TableProject folders owned by users.RLS: auth.uid() = user_idUsed by: Project CRUD operations (src/lib/projects.ts)

public.user_saved_ad_projects

Type: TableMany-to-many links between saved ads and projects.RLS: auth.uid() = user_idUsed by: Project assignment logic

public.user_saved_ads_feed_v1

Type: ViewJoins user_saved_ads + ads_feed_v2 for saved-only feed.Queried by: Dashboard (saved scope)

public.user_project_ads_feed_v1

Type: ViewJoins user_saved_ad_projects → user_saved_ads → ads_feed_v2 for project-scoped feed.Queried by: Dashboard (project scope)

public.page_rip_log

Type: TableRate-limiting log for Page Ripper captures.Access: Service role only (bypasses RLS)Used by: /api/download-page for 10 captures / 15 min enforcement

public.fanbasis_webhook_log

Type: TableLogs all Fanbasis webhook events for audit trail.Used by: /api/fanbasis/webhook

public.integration_secrets

Type: TableEncrypted storage for third-party integration secrets (e.g., Fanbasis webhook secret).Access: Service role only

Migrations

All schema changes are managed via Supabase migrations in supabase/migrations/:

20260223083000_create_ads_feed_v2_and_saved_ads.sql — Core feed and saved ads
20260224123000_projects_save_system_v3.sql — Projects and project-ad links
20260224190000_prioritize_high_quality_media_urls.sql — Media URL prioritization
20260225010000_add_app_settings_table.sql — App settings persistence
20260225020000_add_fanbasis_tables.sql — Fanbasis integration tables
20260226052000_add_integration_secrets_table.sql — Encrypted secrets storage
20260227_create_page_rip_log.sql — Page Ripper rate limiting
20260223091000_harden_legacy_security_objects.sql — Optional hardening (drops legacy tables)

Security Model

Row-Level Security (RLS)

All user-scoped tables enforce RLS policies:

user_saved_ads
user_projects
user_saved_ad_projects

CREATE POLICY "Users can manage own saved ads"
ON public.user_saved_ads
FOR ALL
USING (auth.uid() = user_id);

CREATE POLICY "Users can manage own projects"
ON public.user_projects
FOR ALL
USING (auth.uid() = user_id);

CREATE POLICY "Users can manage own project links"
ON public.user_saved_ad_projects
FOR ALL
USING (auth.uid() = user_id);

Authentication

Provider: Supabase Auth
Methods: Magic Link (email) + Google OAuth
Session Storage: localStorage (Supabase client default)
Redirect URLs: Configured via VITE_MAGIC_LINK_REDIRECT_URL and Supabase Dashboard

Admin Authorization

Admin status is stored in auth.users.raw_app_meta_data.user_type:

// src/App.tsx
const isAdmin = user?.user_metadata?.user_type === 'admin';

Admin-only routes and API endpoints check this field before rendering or processing requests.

SSRF Protection (Page Ripper)

The /api/download-page endpoint implements multi-layer SSRF protection:

Hostname Blocklist

Reject private/internal IP ranges, localhost, and metadata endpoints.

DNS Resolution Check

Resolve hostname to IP and re-validate against the blocklist.

Post-Redirect Verification

After Puppeteer navigation, verify the final URL didn’t redirect to a blocked host.

Build and Deployment

Build Process

npm run build executes scripts/build-site.mjs:

Clean Output

Remove and recreate dist/ directory.

Build SPA

Run npm run build:app (Vite build) → outputs to dist/app/.

Duplicate Shell

Copy dist/app/index.html to dist/index.html so / and /app share the same SPA entry.

Copy Favicon

Copy favicon.ico if present.

Deployment Workflow

AdRecon uses a strict 2-lane deployment model:

Staging
Production

npm run deploy:staging

Enforces staging branch checkout
Deploys to Vercel Preview environment
Script: ./scripts/deploy-vercel.sh staging

npm run deploy:production

Enforces main branch checkout
Deploys to Vercel Production environment
Script: ./scripts/deploy-vercel.sh production

The deploy script blocks deployments from the wrong branch to prevent accidental production releases from staging.

Vercel Configuration

vercel.json defines:

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "rewrites": [
    { "source": "/", "destination": "/app/index.html" },
    { "source": "/index.html", "destination": "/app/index.html" },
    { "source": "/admin", "destination": "/app/index.html" },
    { "source": "/admin/:path*", "destination": "/app/index.html" },
    { "source": "/profile", "destination": "/app/index.html" },
    { "source": "/profile/:path*", "destination": "/app/index.html" },
    { "source": "/app", "destination": "/app/index.html" },
    { "source": "/app/:path*", "destination": "/app/index.html" }
  ]
}

Environment Variables

Frontend Variables

VITE_SUPABASE_URL

string

required

Supabase project URL for frontend client initialization

VITE_SUPABASE_ANON_KEY

string

required

Supabase anonymous (public) key for RLS-enforced queries

VITE_MAGIC_LINK_REDIRECT_URL

string

Override for magic link auth redirect (defaults to <origin>/app)

Backend Variables

SUPABASE_URL

string

required

Supabase URL for serverless functions (admin operations)

SUPABASE_SERVICE_ROLE_KEY

string

required

Service role key for RLS-bypassing admin operations

FANBASIS_API_KEY

string

API key for Fanbasis integration actions

FANBASIS_MAGIC_LINK_REDIRECT_URL

string

Server-side redirect override for Fanbasis purchase magic links

ADMIN_RESET_REDIRECT_URL

string

Password reset email redirect target for admin-created users

APIFY_TOKEN

string

Apify API token for Landing Ripper actor runs (legacy, unused by current Page Ripper)

APIFY_LANDING_RIPPER_ACTOR_ID

string

Apify actor ID (legacy, unused by current Page Ripper)

APIFY_LANDING_RIPPER_WEBHOOK_SECRET

string

Webhook validation secret (legacy, unused by current Page Ripper)

APP_BASE_URL

string

Absolute public app URL for building webhook/download links

System Diagram

Performance Considerations

Direct Database Queries

Frontend queries Supabase directly (no API middleware) for minimal latency. RLS enforcement happens at the database layer.

Media Proxy Caching

/api/ad-media can be extended with CDN caching headers to reduce external fetch frequency.

Feed Pagination

Dashboard implements offset-based pagination with configurable page size to manage large result sets.

Serverless Cold Starts

Page Ripper and admin endpoints may experience cold starts (1-3 seconds). Consider warming functions for critical paths.

Get Started

Core Features

User Management

Integrations

​Overview

​Stack Components

Frontend

Backend

Hosting

Capture Pipeline

​Runtime Topology

​Hosting Model

​Route Architecture

​SPA Routing Logic

​Data Flow

​Feed Query Architecture

​Saved Ads Persistence

​Project Management

​Serverless API Functions

​Media Proxy (/api/ad-media)

​Admin User Management (/api/admin/users)

​Fanbasis Integration (/api/admin/fanbasis)

​Fanbasis Webhook (/api/fanbasis/webhook)

​Page Ripper (/api/download-page)

​Database Schema

​Core Tables and Views

​Migrations

​Security Model

​Row-Level Security (RLS)

​Authentication

​Admin Authorization

​SSRF Protection (Page Ripper)

​Build and Deployment

​Build Process

​Deployment Workflow

​Vercel Configuration

​Environment Variables

​Frontend Variables

​Backend Variables

​System Diagram

​Performance Considerations

Direct Database Queries

Media Proxy Caching

Feed Pagination

Serverless Cold Starts

​Next Steps

Back to Introduction

Quickstart Guide

Build docs developers (and LLMs) love

Overview

Stack Components

Runtime Topology

Hosting Model

Route Architecture

SPA Routing Logic

Data Flow

Feed Query Architecture

Saved Ads Persistence

Project Management

Serverless API Functions

Media Proxy (`/api/ad-media`)

Admin User Management (`/api/admin/users`)

Fanbasis Integration (`/api/admin/fanbasis`)

Fanbasis Webhook (`/api/fanbasis/webhook`)

Page Ripper (`/api/download-page`)

Database Schema

Core Tables and Views

Migrations

Security Model

Row-Level Security (RLS)

Authentication

Admin Authorization

SSRF Protection (Page Ripper)

Build and Deployment

Build Process

Deployment Workflow

Vercel Configuration

Environment Variables

Frontend Variables

Backend Variables

System Diagram

Performance Considerations

Next Steps