Project Structure
Full directory layout with explanations.
Root
kinetic-email/
├── api/ # Vercel serverless functions (backend)
├── convex/ # Convex real-time tracking schema & functions
├── database/ # Supabase SQL migrations (01 → 102, numbered)
├── docs-site/ # This documentation site (Docusaurus)
├── e2e/ # Playwright end-to-end tests
├── email-templates/ # Email HTML templates
├── public/ # Static assets (robots.txt, favicons)
├── scripts/ # Build scripts (prerender, sitemap)
├── src/ # Frontend React application
├── tests/ # Vitest test suite
├── CLAUDE.md # AI assistant project instructions
├── PLAN-*.md # Feature design docs (auth, arc, workspace DB, RAG migration)
├── vercel.json # Vercel deployment config
├── vite.config.ts # Vite build config
├── vitest.config.ts # Test runner config
├── playwright.config.ts # E2E test config
├── tailwind.config.js # Tailwind CSS config
└── package.json
api/ — Serverless Functions
api/
├── _auth.ts # Auth middleware (verifyUser, verifyAdmin, spendTokensServer)
├── _telegram.ts # Shared Telegram alert helper
├── _stampTrackingTokens.ts # Tracking token injection helper
├── _unsubscribe-token.ts # HMAC unsubscribe token helper
├── _validate-kinetic.js # Deterministic auto-fix tiers for generated HTML
├── generate.js # Main AI email generation (RAG pipeline)
├── generate-email.ts # Simple Claude email generation (no RAG)
├── send-email-mailgun.ts # Send via Mailgun (all sends, AMP raw MIME)
├── mailgun-webhook.ts # Mailgun delivery/bounce/complaint webhooks (HMAC-verified)
├── unsubscribe.ts # Unsubscribe (verified session or signed HMAC token)
├── deploy-email.ts # Email deployment operations (admin)
├── track-pixel.ts # Tracking pixel endpoint → Convex
├── track-amp-event.ts # AMP interaction tracking → Convex
├── view-email.ts # "View in Browser" — serves stored email HTML
├── validate-amp.ts # AMP4Email validation
├── notify-error.ts # Error notification endpoint
├── notify-signup.ts # Signup alert (Supabase webhook + shared secret)
├── blog-og.ts # Dynamic OG image generation
├── rag-stats.js # Public RAG knowledge base stats (/how-it-works)
├── gen/
│ ├── copy.js # Staged copy generation (Haiku)
│ ├── blueprint.js # Staged blueprint generation (Haiku)
│ └── continuity.js # Brand/prompt mismatch pre-check (Haiku, non-blocking)
├── eval/
│ └── judge.js # LLM judge for the eval harness (Sonnet, admin-only)
├── lib/
│ ├── qa-checks.js # 26 deterministic email QA checks
│ └── style-theories.js # Brand-level style theories (construction rules)
└── admin/
├── submit-content.js # Upload content to Pinecone RAG + rag_documents
├── update-content.js # Update RAG content
├── delete-content.js # Remove from Pinecone
├── list-content.js # Browse RAG library
├── rag-stats.js # RAG database statistics (admin)
├── auto-tag.js # AI content auto-tagging
├── eval.js # Eval harness run/result CRUD (service-role storage)
└── submit-feedback.js # User feedback collection
All routes authenticate through the single shared api/_auth.ts module (imported with a .js extension — the api/ directory is ESM).
src/ — Frontend Application
src/
├── pages/
│ ├── home/ # Landing page (HomePage.tsx)
│ ├── playground/ # AI Playground (PlaygroundPage.tsx)
│ ├── learn/ # Developer course (6 modules)
│ ├── learn-marketing/ # Marketing course (5 modules)
│ ├── learn-coding/ # Coding 101 course (5 modules)
│ ├── learn-prompting/ # AI Prompt Lab course (3 modules)
│ ├── workspace/ # User workspace (dashboard, emails, projects, brands)
│ ├── admin/ # Station admin dashboard
│ ├── examples/ # Interactive code examples
│ ├── blog/ # Blog listing & post pages (content lives in src/content/blog/)
│ ├── portfolio/ # Email showcase gallery
│ ├── render-simulator/ # Multi-client email previewer
│ ├── tutorials/ # Tutorial pages
│ ├── share/ # Public share pages (arcs)
│ ├── unsubscribe/ # Unsubscribe landing page
│ ├── auth/ # Login page
│ ├── profile/ # User profile
│ ├── about/ # How it works
│ ├── media/ # Media page
│ ├── legal/ # Legal pages
│ ├── courses/ # Course hub (redirects to /learn)
│ └── changelog/ # Platform changelog
├── components/
│ ├── admin/ # Station admin components
│ ├── auth/ # Auth-related UI
│ ├── blog/ # Blog components
│ ├── common/ # Shared components (Navigation, Footer, SendEmailModal)
│ ├── email-examples/ # Interactive email demo components
│ ├── layout/ # MainLayout wrapper
│ ├── learn/ # Course components
│ ├── playground/ # Playground-specific components
│ ├── referrals/ # Referral UI
│ ├── simulator/ # Render simulator components
│ ├── visualization/ # Charts and data visualization
│ └── workspace/ # Workspace components
├── content/
│ └── blog/ # Blog posts as code (blog_posts table was dropped)
├── contexts/
│ ├── AuthContext.tsx # Authentication state & methods
│ ├── TokenContext.tsx # Token balance & spending
│ ├── LearningProgressContext.tsx # Course progress tracking
│ ├── LoginModalContext.tsx # Login modal state
│ └── ToastContext.tsx # Toast notifications
├── hooks/
│ ├── useTokenGate.ts # Token pre-check before actions
│ ├── useBlogPost.ts / useBlogPosts.ts / useBlogUnread.ts # Blog content & read state
│ ├── useCurrentTutorial.ts # Tutorial state
│ ├── useExampleAsset.ts # Example asset loading
│ ├── useScrollAnimation.ts # Scroll animation
│ └── useReferralCapture.ts # Referral code tracking
├── lib/
│ ├── supabase.ts # Supabase client (PKCE) + auth header helpers
│ ├── styleTheories.ts # Style theory definitions (frontend mirror)
│ ├── extractDesignTokens.ts # Brand design token extraction
│ ├── productCsv.ts # Brand product catalog CSV import
│ ├── emailTransform.ts # Email HTML transformation utilities
│ ├── emailCompatData.ts # Email client compatibility data
│ └── notifyError.ts # Error reporting
├── seo/
│ ├── seoConfig.ts # Route-level SEO metadata
│ └── SEOHead.tsx # SEO head component (meta, robots)
├── routes.tsx # Route definitions (React Router 7)
├── styles/ # Global CSS
└── types/ # TypeScript type definitions
database/ — SQL Migrations
Over 100 numbered migration files (01 → 102) establishing the Supabase schema, run manually in the Supabase SQL editor:
database/
├── 01-auth-schema.sql # Auth tables
├── 02-main-schema.sql # Core tables
├── ...
├── 59-token-system.sql # Token economy (balances, transactions, RPC functions)
├── ...
├── 97-eval-harness.sql # Eval runs/results (service-role only)
├── 99-rag-documents.sql # RAG source-of-truth HTML (service-role only)
├── 100-style-theory.sql # workspace_emails.style_theory
├── 101-workspace-products.sql # Per-brand product catalogs
└── 102-brand-style-theory.sql # workspace_brands.style_theory
Key tables: user_profiles, token_balances, token_transactions, token_config, referral_codes, learning_progress, admin_users, workspace_emails, workspace_projects, workspace_brands, workspace_products, rag_documents, eval_runs/eval_results, email_suppressions, email_delivery_events
convex/ — Real-Time Tracking
convex/
├── schema.ts # Convex database schema
├── tracking.ts # Tracking event mutations/queries
└── actions.ts # Convex actions