Initial project commit for Coolify staging

2026-08-03 10:45:41 -04:00
commit 70daeb214a
1199 changed files with 243503 additions and 0 deletions
@@ -0,0 +1,203 @@
+# 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.