# meSEO — AI-Powered SEO & LLMO Intelligence Platform

meSEO is a comprehensive SEO and Large Language Model Optimization (LLMO) intelligence platform with first-party cookieless tracking, universal form/booking plugin detection, and AI-powered content optimization.

**Production:** [app.meseoapp.com](https://app.meseoapp.com)
**Admin Portal:** [admin.meseoapp.com](https://admin.meseoapp.com)

## Tech Stack

- **Frontend:** Next.js 14 (App Router) + TypeScript + Tailwind CSS
- **Database:** Neon PostgreSQL + Prisma ORM
- **Auth:** Clerk (organizations + role-based access)
- **AI:** Anthropic Claude + OpenAI
- **SERP Data:** DataForSEO
- **Hosting:** Vercel
- **Analytics Sources:** Google Analytics 4 (GA4), Google Search Console (GSC), First-Party Site Tag

## Architecture

```
app.meseoapp.com        → Main application (brand owners, agencies)
admin.meseoapp.com      → Admin portal (superadmin operations center)
/api/collect            → Site Tag event ingestion endpoint
/api/cron/*             → Scheduled jobs (data retention, platform snapshots)
```

Same Vercel project, hostname-based middleware routing.

## Core Features

### Site Tag (First-Party Tracking)
- **Cookieless** — zero `document.cookie` usage, sessionStorage/localStorage only
- **Universal form detection** — native `<form>`, `[role="form"]`, container-based, standalone inputs
- **Booking plugin detection** — Amelia (Elementor Step Booking variant), Calendly, NexHealth, Acuity, JotForm, Typeform, WPForms, Gravity Forms, Contact Form 7, HubSpot
- **Chat widget detection** — DearDoc, Birdeye, Podium, Weave
- **Device + geolocation** — User-Agent parsing (device/browser/OS) + Vercel geo headers (country, city, region) stored on session start
- **21 healthcare iframe providers** detected (PatientPop, Tebra, NexHealth, MyChart, Epic, Cerner, athenahealth, Doctible, etc.)
- **gtag/dataLayer interception** — captures GA4 custom events (make_an_appointment, contact_us, etc.) with pattern-based fallback matching
- **Form & Booking Funnel** — Intent → Started → Submitted → Confirmed with per-stage drop-off
- **Conversion taxonomy** — Tier 1 (hard: appointment_booked, form_submitted, phone_call, purchase) vs Tier 2 (soft: appointment_attempted, form_started, appointment_intent)
- **30-second dedup window** with source-authority ranking and tier-upgrade
- **HIPAA-aware** — never captures form field values, strips query params in healthcare mode
- **3,400+ lines** of tracking intelligence in `public/t.js`

### Intelligence Pages
- **Dashboard** — All Traffic / Organic toggle, KPI cards, tail cards
- **Site Tag Analytics** — Live polling, event breakdown, form funnel, detected plugins, data confidence gauge
- **AI Visibility** — LLM citation checking across ChatGPT, Gemini, Perplexity
- **Keyword Research** — SERP analysis + keyword opportunities
- **Rank Tracker** — Daily position monitoring
- **Competitor Intel** — Keyword battles, word count analysis, SERP overlap
- **Content Intel** — Content health scoring, accordion tiles
- **Backlinks** — Backlink profile analysis
- **Industry Intel** — 10-vertical regulatory map, visitor geography, seasonal correlations
- **Technical Audit** — 200-page crawl with incremental progress
- **Core Web Intelligence** — Multi-page CWV with competitor comparison
- **Schema Generator** — JSON-LD generation with validation
- **Broken Links** — Site-wide broken link detection
- **Signals Center** — Persistent dismiss with 14-day TTL, revenue impact badges

### Content & Reports
- **SEO Content Brief** — AI-generated briefs with inline schema
- **LLMO Content Brief** — LLM optimization briefs
- **Writing Assistant** — AI-powered content rewriting
- **Page Studio** — Page creation and optimization
- **Topic Map** — Content cluster visualization
- **Report Studio** — Automated report generation

### Settings
- **Profile** — Editable name, avatar upload via Clerk, IANA timezone dropdown, change password
- **Billing** — Real plan data, trial countdown, change plan / manage billing links
- **Notifications** — 5 email preference toggles with optimistic update
- **Team** — Per-member brand access, seat count display, role management, invite with seat limit enforcement
- **Usage** — 8 metrics with progress bars, color-coded thresholds, unlimited tier gradient bars

### Admin Portal (admin.meseoapp.com)
- **Dashboard** — Platform KPIs with Site Tag / GA4 / GSC data source separation, brand filter, reconciliation
- **Users** — Search, role filter, detail drawer, suspend/delete/brand-grant actions
- **Brands** — Health ring, integration status dots, detail drawer with radar chart
- **Session Explorer** — Per-session interaction timeline with device/location, repeat interaction highlighting
- **AI Monitor** — Guardrail scoring, severity-colored feed, cost-by-brand breakdown
- **Platform Analytics** — Brand Strength Radar (8 dimensions), Engagement (DAU/WAU/MAU + cohort retention), Data Moat, Growth & Retention (activation funnel + churn)
- **Cost Center** — All vendor costs (Anthropic, OpenAI, Neon, Vercel, Clerk, DataForSEO, Resend) with live DataForSEO balance
- **Compliance** — GDPR Article 17 deletion, Article 15 export, data retention cron, healthcare mode
- **Data Export** — 4 due-diligence CSV exports (platform metrics, anonymized users, brands, growth time-series)
- **Health Monitor** — DB row counts, cron status, recent errors
- **Activity Feed** — Real-time 10s polling with connected timeline
- **Conversion Funnel** — 5-stage funnel (Visit → Engaged → Intent → Started → Converted) with by-source and by-entry-page breakdowns
- **Client Portal** — White-label setup, custom domain config, per-client page access controls, branded invite emails

### Monetization
- **5 pricing tiers:** Growth ($249), Professional ($479), Agency ($1,299), Agency Pro ($2,499), Enterprise (Custom)
- **Feature gates** — `<FeatureGate>` component + `useFeatureGate` hook + server-side `requirePlanFeature`
- **Seat limits** — 2/5/10/25/unlimited per plan with enforcement at invite time
- **Upgrade modal** — Auto-opens on 403 upgrade_required via `useUpgradeAwareFetch`
- **Sidebar lock icons** — 15 protected routes mapped to feature keys
- **Superadmin bypass** — all gates skip for superadmin role

### Security & Access Control
- **BrandMembership** — Explicit brand access grants (not implicit org-wide)
- **`verifyBrandAccess`** — Per-request brand authorization with audit logging
- **`NoBrandAccessGuard`** — Redirects users with 0 brands to /no-access
- **Superadmin** — Clerk publicMetadata.role via customized session token

### Conversion Accuracy
- **Conversion taxonomy** — canonical types with Tier 1/2 classification
- **Conversion resolver** — 30s dedup window, source-authority ranking, tier-upgrade in-place
- **GA4 reconciliation** — overlapping-window comparison with daily rates
- **Data confidence gauge** — 6-factor weighted score (session match, conversion capture, freshness, dedup quality, event coverage, plugin detection)
- **Deduped KPIs** — COUNT(DISTINCT session+page+type), not raw row count

## Environment Variables

```
# Database
DATABASE_URL=                    # Neon PostgreSQL pooler endpoint

# Auth
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
CLERK_SECRET_KEY=

# AI
ANTHROPIC_API_KEY=
OPENAI_API_KEY=

# SERP Data
DATAFORSEO_LOGIN=
DATAFORSEO_PASSWORD=

# Google
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GA4_PROPERTY_ID=

# App
NEXT_PUBLIC_APP_URL=https://app.meseoapp.com
```

## Clerk Session Token

In Clerk Dashboard → Configure → Sessions → Customize session token:

```json
{
  "metadata": "{{user.public_metadata}}"
}
```

Required for superadmin role detection in middleware.

## Cron Jobs

| Schedule | Endpoint | Purpose |
|----------|----------|---------|
| Daily 03:00 UTC | `/api/cron/data-retention` | Purge data older than retention period (395 days default) |
| Monthly 1st 01:00 UTC | `/api/cron/platform-snapshot` | Capture platform metrics snapshot |

## Key Architectural Decisions

- **Same Vercel project** for app + admin, hostname-based middleware routing
- **Cookieless tracking** via sessionStorage/localStorage — no cookie consent needed
- **Conversion taxonomy** with Tier 1 (hard) vs Tier 2 (soft) — only Tier 1 counts in KPIs
- **gtag/dataLayer interception** as primary conversion source for GA4-instrumented sites
- **30-second dedup window** with tier-upgrade for conversion resolver
- **DataForSEO** never mentioned in user-facing UI — labeled "SERP & Keyword Lookups"
- **Site Tag** at 3,400+ lines with universal plugin detection (10 booking + 4 chat providers)
- **PlatformEvent + AiInteraction** telemetry with fire-and-forget pattern

## Site Tag Detection Patterns

The Site Tag (`public/t.js`) detects third-party plugins and integrations running on a brand's site and fires `plugin_detected` events. Detection patterns live in the unminified source file, which is gitignored:

**Detection source:** `public/t.source.js`
Three registries:
- `BOOKING_PLUGINS` (~line 5832) -- appointment and form plugins
- `CHAT_WIDGETS` (~line 6416) -- live chat and messaging widgets
- `ANALYTICS_PLUGINS` (~line 6659) -- analytics, pixels, SEO, CMS, e-commerce, CRM, and more (~47 entries)

**Enrichment metadata:** `src/lib/site-tag/integration-signatures.ts`
Maps each `plugin_key` to vendor name, category, and description. Consumed by the backfill route and the Integrations tab API.

**Adding a new detection rule:**
1. Add an entry to the appropriate registry in `public/t.source.js`
2. Add a matching entry in `ENRICHMENT_REGISTRY` in `integration-signatures.ts`
3. Build the tag: `cp public/t.source.js public/t.js && npm run build:site-tag`
4. Bump `TAG_VERSION` in `public/t.js` to today's date (`YYYY.MM.DD`)

See `docs/phase-30-site-tag-detection-expansion.md` for the full pattern guide, detection strategy examples, and performance constraints.

## Development

```bash
npm install
npx prisma db push
npx prisma generate
npm run dev
```

Local admin portal: `admin.localhost:3000`

## License

Proprietary — All rights reserved.