Skip to main content

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 (60+ files, numbered)
├── docs/                   # Internal technical docs (architecture notes, analyses)
├── docs-site/              # This documentation site (Docusaurus)
├── public/                 # Static assets (robots.txt, favicons)
├── rag-blogs/              # RAG knowledge base (16 markdown articles)
├── scripts/                # Build scripts (prerender, sitemap)
├── src/                    # Frontend React application
├── tests/                  # Vitest test suite
├── CLAUDE.md               # AI assistant project instructions
├── GRANDPLAN.md            # Full ESP roadmap document
├── workspace.md            # Workspace feature design doc
├── view-in-browser.md      # Hosted email system design doc
├── vercel.json             # Vercel deployment config
├── vite.config.ts          # Vite build config
├── vitest.config.ts        # Test runner config
├── tailwind.config.js      # Tailwind CSS config
└── package.json

api/ — Serverless Functions​

api/
├── _auth.ts                # Auth middleware (verifyUser, verifyAdmin, spendTokensServer)
├── _telegram.ts            # Telegram bot webhook handler
├── generate.js             # Main AI email generation (RAG pipeline, ~1200 lines)
├── generate-email.ts       # Simple Claude email generation (no RAG)
├── send-email.ts           # Send via Resend
├── send-email-ses.ts       # Send via AWS SES
├── deploy-email.ts         # Email deployment operations
├── track-pixel.ts          # Tracking pixel endpoint → Convex
├── validate-amp.ts         # AMP4Email validation
├── resend-status.ts        # Delivery status checking
├── notify-error.ts         # Error notification endpoint
├── blog-og.ts              # Dynamic OG image generation
├── lib/
│   └── qa-checks.js        # Email QA scoring logic
└── admin/
    ├── _auth.js             # Admin auth middleware (JS mirror of _auth.ts)
    ├── submit-content.js    # Upload content to Pinecone RAG
    ├── update-content.js    # Update Pinecone content
    ├── delete-content.js    # Remove from Pinecone
    ├── list-content.js      # Browse RAG library
    ├── rag-stats.js         # RAG database statistics
    ├── auto-tag.js          # AI content auto-tagging
    ├── run-evaluation.js    # QA evaluation runner
    ├── submit-evaluation.js # Save evaluation results
    ├── list-evaluations.js  # Retrieve evaluations
    └── submit-feedback.js   # User feedback collection

src/ — Frontend Application​

src/
├── pages/
│   ├── home/               # Landing page (HomePage.tsx)
│   ├── playground/         # AI Playground (PlaygroundPageV2.tsx)
│   ├── learn/              # Developer course (6 modules)
│   ├── learn-marketing/    # Marketing course (5 modules)
│   ├── learn-coding/       # Coding 101 course (5 modules)
│   ├── workspace/          # User workspace (dashboard, emails, projects, brands)
│   ├── admin/              # Station admin dashboard
│   ├── examples/           # Interactive code examples
│   ├── blog/               # Blog listing & post pages
│   ├── portfolio/          # Email showcase gallery
│   ├── render-simulator/   # Multi-client email previewer
│   ├── auth/               # Login page
│   ├── profile/            # User profile
│   ├── about/              # How it works
│   ├── media/              # Media page
│   ├── 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
│   ├── playground/         # Playground-specific components
│   ├── visualization/      # Charts and data visualization
│   └── workspace/          # Workspace components
├── 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      # Blog post data fetching
│   ├── useScrollAnimation.ts       # Scroll animation
│   └── useReferralCapture.ts       # Referral code tracking
├── lib/
│   ├── supabase.ts         # Supabase client + auth helpers
│   ├── 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)
├── styles/                 # Global CSS
├── types/                  # TypeScript type definitions
└── utils/                  # General utilities

database/ — SQL Migrations​

Over 60 numbered migration files establishing the Supabase schema:

database/
├── 01-schema.sql           # Core tables
├── 02-auth.sql             # Auth setup
├── ...
├── 59-token-system.sql     # Token economy (balances, transactions, RPC functions)
├── 60-security.sql         # Security hardening
└── ...

Key tables: user_profiles, token_balances, token_transactions, token_config, referral_codes, learning_progress, admin_users, blog_posts, workspace_emails, workspace_projects, workspace_brands

convex/ — Real-Time Tracking​

convex/
├── schema.ts               # Convex database schema
├── trackingEvents.ts       # Tracking event mutations/queries
└── ...