Skip to main content

Architecture Overview

Kinetic Email is a modern web application built on a serverless architecture with multiple specialized services handling different concerns.

High-Level Architecture​

┌──────────────────────────────────────────────────────┐
│                    Vercel (Hosting)                    │
│  ┌──────────────┐  ┌──────────────────────────────┐  │
│  │  React SPA   │  │  Serverless API Functions     │  │
│  │  (Vite)      │  │  /api/generate.js             │  │
│  │              │  │  /api/send-email-mailgun.ts    │  │
│  │  Pages:      │  │  /api/track-pixel.ts           │  │
│  │  - Playground│  │  /api/gen/* /api/admin/*       │  │
│  │  - Courses   │  │                                │  │
│  │  - Workspace │  └──────────┬──────┬──────┬───────┘  │
│  │  - Station   │             │      │      │          │
│  └──────┬───────┘             │      │      │          │
└─────────┼─────────────────────┼──────┼──────┼──────────┘
          │                     │      │      │
    ┌─────▼─────┐   ┌──────────▼┐  ┌──▼────┐ │
    │ Supabase  │   │ Anthropic │  │Mailgun│ │
    │ Auth + DB │   │ Claude AI │  │ Email │ │
    │ RLS + RPC │   └───────────┘  └───────┘ │
    └───────────┘                       ┌────▼─────┐
                                        │ Pinecone │
    ┌───────────┐                       │ Vector   │
    │  Convex   │                       │ Search   │
    │ Real-time │                       └──────────┘
    │ Tracking  │
    └───────────┘

Core Services​

Frontend (React + Vite)​

The single-page application handles all user-facing pages. Routes are code-split with lazy loading and retry logic for chunk loading errors. The app uses React Router v7 with nested layouts.

Key areas:

  • Playground (/playground) — AI email generation interface
  • Learning Hub (/learn) — Three structured courses
  • Workspace (/workspace) — User project management
  • Station (/station) — Admin dashboard
  • Portfolio (/portfolio) — Email showcase gallery
  • Blog (/blog) — Content platform

Serverless API (Vercel Functions)​

All backend logic runs as Vercel serverless functions in the api/ directory. Functions handle:

  • AI email generation with RAG context (staged copy → blueprint → code pipeline)
  • Email delivery via Mailgun (including AMP4Email raw MIME)
  • Interaction tracking, unsubscribe, and delivery webhooks
  • Admin operations (RAG content management, eval harness)

Note: api/ runs as ESM — relative imports must carry the .js extension (even for .ts sources) or the function crashes at module load on Vercel.

Database (Supabase)​

PostgreSQL with Row-Level Security (RLS) on all tables handles:

  • User authentication (PKCE flow: email/password, magic link, Google OAuth)
  • User profiles and preferences
  • Token balances and transactions
  • Learning progress tracking
  • Workspace data (emails, projects, brands, product catalogs)
  • Server-only data (RAG documents, eval runs, delivery events, suppressions)

Real-Time Tracking (Convex)​

Convex provides real-time data for:

  • Email open tracking via tracking pixels
  • Interaction event logging (tab clicks, survey responses)
  • Live analytics in the Station dashboard

AI System (Anthropic + Pinecone + OpenAI)​

The email generation pipeline combines:

  • Pinecone — Vector index (RAG v2) storing embeddings for kinetic email examples and knowledge articles; full example HTML lives in the Supabase rag_documents table (service-role only)
  • OpenAI — Generates embeddings for vector search (text-embedding-3-large)
  • Anthropic Claude — Haiku for copy, blueprints, and re-ranking; Sonnet for HTML generation
  • See RAG Overview for the full pipeline

Email Delivery (Mailgun)​

Mailgun is the sole delivery provider — it handles all sends, including AMP4Email via raw MIME (api/send-email-mailgun.ts). Delivery, bounce, and complaint webhooks feed the suppression list and Station dashboard. (Resend and SES were fully retired — see Email Provider Migration.)

Data Flow: Email Generation​

User Prompt
    │
    ▼
Frontend (useTokenGate → pre-check balance)
    │
    ▼
POST /api/generate.js (verifyUser → spendTokensServer)
    │
    ├── Extract technique from prompt
    │
    ├── Parallel Pinecone queries (v2 index):
    │   ├── Query A: technique-filtered (topK=10)
    │   └── Query B: broad unfiltered (topK=15)
    │
    ├── Merge + deduplicate results
    │
    ├── Re-rank with Claude Haiku (select best 7)
    │
    ├── Fetch full example HTML from Supabase rag_documents
    │
    ├── Build context (CODE EXAMPLES + KNOWLEDGE)
    │
    ├── Blueprint with Claude Haiku (copy + design tokens;
    │   brand design tokens force-merged — brand always wins)
    │
    ├── Generate HTML with Claude Sonnet (kinetic + AMP in parallel)
    │
    ├── QA checks (26 deterministic checks) + auto-fix tiers
    │
    └── Return HTML + usage stats

The Playground stages copy and blueprint generation through /api/gen/copy and /api/gen/blueprint (both Haiku) before calling /api/generate with the pre-built blueprint. /api/gen/continuity runs a non-blocking brand/prompt mismatch check.

Data Flow: Email Sending​

Generated HTML
    │
    ▼
Frontend (useTokenGate → pre-check balance)
    │
    ▼
POST /api/send-email-mailgun.ts (verifyUser — sender is the verified account)
    │
    ├── Check suppression list (bounces/complaints) before sending
    ├── Inject tracking pixels (UUID, SEND_ID, TIMESTAMP)
    ├── Add attribution banner + "View in Browser" link
    ├── Sanitize sender email (XSS prevention)
    │
    └── Send via Mailgun API (raw MIME for AMP4Email)
         │
         └── Recipient opens email
              │
              └── Tracking pixel fires → /api/track-pixel.ts → Convex