meseo-staging/README.md

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 Admin Portal: 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:

{
  "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

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

Local admin portal: admin.localhost:3000

License

Proprietary — All rights reserved.