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.ts            │  │
│  │  Pages:      │  │  /api/track-pixel.ts           │  │
│  │  - Playground│  │  /api/admin/*                  │  │
│  │  - Courses   │  │                                │  │
│  │  - Workspace │  └──────────┬──────┬──────┬───────┘  │
│  │  - Station   │             │      │      │          │
│  └──────┬───────┘             │      │      │          │
└─────────┼─────────────────────┼──────┼──────┼──────────┘
          │                     │      │      │
    ┌─────▼─────┐   ┌──────────▼┐  ┌──▼───┐  │
    │ Supabase  │   │ Anthropic │  │Resend│  │
    │ Auth + DB │   │ Claude AI │  │ SES  │  │
    │ 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 v6 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
  • Email delivery via Resend/SES
  • Interaction tracking
  • Admin operations (RAG content management, evaluations)

Database (Supabase)​

PostgreSQL with Row-Level Security (RLS) handles:

  • User authentication (magic link, Google OAuth, email/password)
  • User profiles and preferences
  • Token balances and transactions
  • Learning progress tracking
  • Blog content storage
  • Workspace data (emails, projects, brands)

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 database storing kinetic email examples and knowledge articles
  • OpenAI — Generates embeddings for vector search
  • Anthropic Claude — Generates email HTML using RAG-retrieved context
  • See RAG Overview for the full pipeline

Email Delivery (Resend + AWS SES)​

Two delivery providers:

  • Resend — Primary provider, handles most email sends
  • AWS SES — Fallback provider for high-volume or specialized sends

Data Flow: Email Generation​

User Prompt
    │
    ▼
Frontend (useTokenGate → pre-check balance)
    │
    ▼
POST /api/generate.js (verifyUser → spendTokensServer)
    │
    ├── Extract technique from prompt
    │
    ├── Parallel Pinecone queries:
    │   ├── Query A: technique-filtered (topK=10)
    │   └── Query B: broad unfiltered (topK=15)
    │
    ├── Merge + deduplicate results
    │
    ├── Re-rank with Claude Haiku (select best 7)
    │
    ├── Build context (CODE EXAMPLES + KNOWLEDGE)
    │
    ├── Generate HTML with Claude Sonnet
    │
    └── Return HTML + usage stats

Data Flow: Email Sending​

Generated HTML
    │
    ▼
Frontend (useTokenGate → pre-check balance)
    │
    ▼
POST /api/send-email.ts (verifyUser → spendTokensServer)
    │
    ├── Inject tracking pixels (UUID, SEND_ID, TIMESTAMP)
    ├── Resolve relative image URLs → absolute
    ├── Add attribution banner (if not self-send)
    ├── Sanitize sender email (XSS prevention)
    │
    └── Send via Resend API
         │
         └── Recipient opens email
              │
              └── Tracking pixel fires → /api/track-pixel.ts → Convex